@parall/parel-channel 1.51.0 → 1.52.0

package/src/catchup.ts

@@ -0,0 +1,337 @@
+import type { ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
+import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
+import { clearForkState, FORK_DISABLED_KEY } from './fork.js';
+import { fetchMainSessionFresh, invalidateChildSession, SESSION_CACHE_KEY } from './session.js';
+
+/**
+ * Incremental, timer-driven dispatch catch-up (execution-model v2 I4:
+ * lifecycle hooks are O(1); any O(backlog) work must be a durable, resumable,
+ * timer-driven job — parel channel-connector-execution-model.md §2).
+ *
+ * The 1.48.0 shape — onOpen sweeping up to 40×50 dispatches inline — cannot
+ * live under the v2 15s onOpen budget (a backlog would blow the budget, and
+ * under first-timeout-terminal semantics every timeout is an epoch rotation:
+ * the sweep would convert a reconnect into a rotation storm). Instead:
+ *
+ *   onOpen  → reset the sweep state, arm CATCHUP_TIMER_KEY at now  (O(1))
+ *   onTimer → one bounded round per firing:
+ *     round 0 (phase 'gen'): the New Session generation check — MUST precede
+ *       any dispatch replay (a rotation that happened while offline would
+ *       otherwise replay post-reset messages into pre-reset forks), plus the
+ *       forkDisabled revalidation-latch clear. Best-effort, same posture the
+ *       onOpen sweep had: a transient failure logs and the sweep proceeds
+ *       (the cached session id — the generation token — is never dropped).
+ *     sweep rounds: ONE page of GET /dispatch, items replayed FIFO through
+ *       the normal dispatch pipeline, then re-arm immediately while pages
+ *       remain. Cursor lives in ctx.store; it is an optimization, not a
+ *       correctness source — the per-source attempt fence (shouldSkipLiveRow)
+ *       makes any re-scan idempotent, so a mid-page bail or a crash simply
+ *       re-lists the same page and skips what already emitted.
+ *     drain: a pass that ends (no next_cursor) after emitting anything runs
+ *       one more pass from the top (rows the cursor walk missed, rows that
+ *       arrived mid-sweep); the job ends on the first CLEAN pass — no emits,
+ *       no item failures. Item failures keep the row pending server-side and
+ *       re-arm the next pass with exponential backoff instead of ending, so
+ *       a transiently unfetchable source is retried without a reconnect.
+ *
+ * FIFO across the live socket: while a sweep is in flight, dispatch.new
+ * frames are NOT processed inline (they would leapfrog the backlog into the
+ * shared main session out of order) — the frame handler just re-arms the
+ * timer (armCatchUpEffect) and lets the sweep list the row, which is already
+ * durable server-side. That re-arm doubles as the lost-timer self-heal: any
+ * new frame revives a stalled sweep. The re-arm honours an in-flight backoff
+ * (state.notBefore): a frame arriving while a round is backed off on a 5xx
+ * source re-arms at the remaining delay, not 0, so steady traffic against a
+ * failing source cannot tight-poll it.
+ *
+ * Runs identically under the v1 host (flag off): timers and effects work the
+ * same there, rounds serialize through the connection hook chain, and the
+ * bounded round size keeps each onTimer call small.
+ */
+
+export const CATCHUP_TIMER_KEY = '__parall_catchup__';
+/** Store key — deliberately OUTSIDE the `fork` prefix family so the
+ * agent.new_session purge (clearForkState) never wipes sweep state. */
+const CATCHUP_STATE_KEY = 'catchup';
+
+/** One page per round; page size == round item bound so a clean round always
+ * advances the cursor. Small on purpose: each item can fan out several inline
+ * fetches and 1-2 effects, and the round's effects execute while the v2
+ * execution slot is held — a big page would occupy it for the whole replay. */
+const CATCHUP_PAGE_LIMIT = 10;
+/** Soft wall-clock bound per round, checked BETWEEN items (an in-flight item
+ * finishes). 4s: the binding constraint is the LEGACY (flag-off) host, whose
+ * hook budget is 5s and whose timeout discards the round's effects — re-arm
+ * included — rather than cancelling the work; staying under it keeps the
+ * common case safe on both hosts (v2's onTimer budget is 60s). A single
+ * pathological item can still blow past any bound (its own fetch caps are
+ * the 5s REQUEST_TIMEOUT_MS); the self-heal for a discarded re-arm is the
+ * frame handler's defer path (any live frame re-arms the timer) plus the
+ * next reconnect's beginCatchUp. */
+const ROUND_SOFT_BUDGET_MS = 4_000;
+/** Timeout for the job's OWN fetches (dispatch page list, generation check).
+ * Tighter than REQUEST_TIMEOUT_MS: on the v1 host these run inside a 5s
+ * onTimer budget whose expiry discards the round's effects AFTER the due
+ * timer row was already deleted — a single stalled request at the full 5s
+ * cap would strand the job with no timer. 3s leaves re-arm margin. */
+const CATCHUP_FETCH_TIMEOUT_MS = 3_000;
+const BACKOFF_BASE_MS = 5_000;
+const BACKOFF_MAX_MS = 5 * 60 * 1000;
+
+interface CatchUpState {
+  phase: 'gen' | 'sweep';
+  cursor: string;
+  /** This pass emitted work or saw item failures — another pass follows. */
+  dirty: boolean;
+  /** Item failures this pass — the follow-up pass arms with backoff. */
+  sawFailure: boolean;
+  /** Consecutive transient failures (page fetch / failed passes) → backoff. */
+  failures: number;
+  /** Absolute ctx.now() before which the sweep timer must NOT fire, or 0 when
+   * unconstrained. Persisted so the FIFO defer path (a live frame re-arming
+   * the keyed timer) honours an in-flight backoff instead of overwriting it
+   * to fire immediately — otherwise a source stuck on 5xx plus steady traffic
+   * would tight-poll the failing API, the exact storm backoffDelay prevents. */
+  notBefore: number;
+}
+
+interface DispatchPage {
+  data?: Record<string, unknown>[];
+  next_cursor?: string;
+}
+
+/** Frozen so the store-less fallback (memoryState, written by reference in
+ * beginCatchUp) cannot be mutated into a corrupted shared template — every
+ * transition already builds a new object via spread. */
+const FRESH_STATE: CatchUpState = Object.freeze({
+  phase: 'gen',
+  cursor: '',
+  dirty: false,
+  sawFailure: false,
+  failures: 0,
+  notBefore: 0,
+});
+
+/** In-memory fallback for store-less contexts (SDK test mocks) — a module
+ * global is a discardable cache, never correctness (v2 I4), which is exactly
+ * the durability class a fallback may have. */
+const memoryState = new Map<string, CatchUpState>();
+
+async function readState(ctx: ConnectorContext): Promise<CatchUpState | null> {
+  if (!ctx.store) return memoryState.get(ctx.connectionId) ?? null;
+  const raw = (await ctx.store.get(CATCHUP_STATE_KEY).catch(() => null)) as CatchUpState | null;
+  return raw && (raw.phase === 'gen' || raw.phase === 'sweep') ? raw : null;
+}
+
+async function writeState(ctx: ConnectorContext, state: CatchUpState): Promise<void> {
+  if (!ctx.store) {
+    memoryState.set(ctx.connectionId, state);
+    return;
+  }
+  await ctx.store.set(CATCHUP_STATE_KEY, state).catch(() => {});
+}
+
+async function clearState(ctx: ConnectorContext): Promise<void> {
+  if (!ctx.store) {
+    memoryState.delete(ctx.connectionId);
+    return;
+  }
+  await ctx.store.delete(CATCHUP_STATE_KEY).catch(() => {});
+}
+
+/** The idempotent "make sure the sweep timer is armed" effect (setTimer is
+ * keyed — re-arming replaces). Also what the frame handler returns while a
+ * sweep is in flight. */
+export function armCatchUpEffect(ctx: ConnectorContext, delayMs = 0): ConnectorEffect {
+  return { type: 'setTimer', key: CATCHUP_TIMER_KEY, at: ctx.now() + delayMs };
+}
+
+/**
+ * onOpen: O(1) by contract — reset the sweep to a fresh pass (a reconnect is
+ * the revalidation point, so the generation check must run again) and arm the
+ * timer. All real work happens in runCatchUpRound.
+ */
+export async function beginCatchUp(ctx: ConnectorContext): Promise<ConnectorEffect[]> {
+  await writeState(ctx, FRESH_STATE);
+  return [armCatchUpEffect(ctx)];
+}
+
+/**
+ * The frame handler's FIFO gate: while a sweep is in flight (state present),
+ * a live dispatch.new must not leapfrog the backlog. Returns the delay (ms)
+ * the caller should re-arm the sweep timer with — honouring any in-flight
+ * backoff (notBefore) so a live frame cannot reset a backed-off round to fire
+ * immediately — or null when no sweep is in flight (process the frame inline).
+ * Also marks the pass dirty so the job runs another from-the-top pass before
+ * ending. The dirty mark is load-bearing, not just ordering hygiene: a server
+ * REDRIVE hint can point at a row BEHIND the sweep cursor (e.g. during the
+ * final re-check pass), and deferring the frame consumes that hint — without
+ * forcing one more full pass, the job could end cleanly with the row
+ * stranded until the next reconnect. Runs inside the serialized chain, so
+ * the read-modify-write cannot interleave with a round's own state write.
+ */
+export async function deferToCatchUp(ctx: ConnectorContext): Promise<number | null> {
+  const state = await readState(ctx);
+  if (!state) return null;
+  if (!state.dirty) await writeState(ctx, { ...state, dirty: true });
+  // Honour an in-flight backoff: re-arming the keyed timer at delay 0 would
+  // overwrite a backoffDelay-armed round and tight-poll a failing source.
+  return Math.max(0, state.notBefore - ctx.now());
+}
+
+function backoffDelay(failures: number): number {
+  return Math.min(BACKOFF_BASE_MS * 2 ** Math.max(0, failures - 1), BACKOFF_MAX_MS);
+}
+
+/**
+ * New Session generation check — verbatim semantics of the 1.48.0 onOpen
+ * preamble (see the session.ts fetchMainSessionFresh doc): the
+ * `agent.new_session` WS push is not replayed, so a reset that happened while
+ * disconnected leaves stale fork routing that would deliver post-reset
+ * messages into pre-reset children. The main ase_ id IS the generation token.
+ */
+async function runGenerationCheck(ctx: ConnectorContext): Promise<void> {
+  try {
+    const cachedMain = (await ctx.store?.get(SESSION_CACHE_KEY).catch(() => null)) as string | null;
+    if (cachedMain) {
+      const freshMain = await fetchMainSessionFresh(ctx, { timeoutMs: CATCHUP_FETCH_TIMEOUT_MS });
+      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(FORK_DISABLED_KEY).catch(() => {});
+  } catch (err) {
+    console.error('[parel-channel] new-session generation check failed', err);
+  }
+}
+
+/**
+ * One timer round. `planDispatch` is the normal inbound dispatch pipeline
+ * (inbound.ts effectsForDispatch), injected to keep this module's imports
+ * acyclic. Every path either re-arms the timer or deliberately ends the job.
+ */
+export async function runCatchUpRound(
+  ctx: ConnectorContext,
+  planDispatch: (data: Record<string, unknown>) => Promise<ConnectorEffect[]>,
+): Promise<ConnectorEffect[]> {
+  // A missing state row (timer armed by a deferred frame racing the sweep's
+  // clean finish, or state lost) starts a fresh sweep — over-sweeping is
+  // idempotent (fences), under-sweeping loses messages.
+  const state = (await readState(ctx)) ?? FRESH_STATE;
+
+  if (state.phase === 'gen') {
+    await runGenerationCheck(ctx);
+    await writeState(ctx, { ...FRESH_STATE, phase: 'sweep' });
+    return [armCatchUpEffect(ctx)];
+  }
+
+  const roundStart = ctx.now();
+  let body: DispatchPage | null = null;
+  try {
+    const apiUrl = parallApiUrl(ctx);
+    const agk = requireAgk(ctx);
+    const orgId = parallOrgId(ctx);
+    const url = `${apiUrl}/api/v1/orgs/${orgId}/dispatch?limit=${CATCHUP_PAGE_LIMIT}${
+      state.cursor ? `&cursor=${encodeURIComponent(state.cursor)}` : ''
+    }`;
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${agk}` },
+      signal: AbortSignal.timeout(CATCHUP_FETCH_TIMEOUT_MS),
+    });
+    if (res.ok) {
+      body = (await res.json().catch(() => null)) as DispatchPage | null;
+    }
+  } catch {
+    // fall through to the transient-failure backoff below
+  }
+  if (!body) {
+    const failures = state.failures + 1;
+    const delay = backoffDelay(failures);
+    // Persist notBefore so a live frame's defer re-arm honours the backoff
+    // instead of resetting it to fire now (tight-polling the failing API).
+    await writeState(ctx, { ...state, failures, notBefore: ctx.now() + delay });
+    console.error(`[parel-channel] catch-up page fetch failed (attempt ${failures})`);
+    return [armCatchUpEffect(ctx, delay)];
+  }
+
+  // Replay SEQUENTIALLY, in page order (FIFO): every envelope feeds the
+  // agent's one main session, so cross-chat replay concurrency would
+  // scramble the session's input order AND race the agent-global
+  // turnEnvelope marker. Transient item failures THROW (the pipeline's
+  // transient-vs-deliberate contract: a 5xx/timeout on a source fetch
+  // throws; deliberate pendings — unknown types, fence skips, disabled
+  // deployments — return []): the row stays pending server-side and the
+  // failure flag re-arms the next pass with backoff instead of ending the
+  // job with the row stranded on a healthy long-lived socket.
+  const rows = body.data ?? [];
+  const effects: ConnectorEffect[] = [];
+  let dirty = state.dirty;
+  let sawFailure = state.sawFailure;
+  let processed = 0;
+  for (const d of rows) {
+    if (ctx.now() - roundStart > ROUND_SOFT_BUDGET_MS) break;
+    const out = await planDispatch(d).catch((err) => {
+      console.error('[parel-channel] catch-up dispatch failed', err);
+      sawFailure = true;
+      dirty = true;
+      return [] as ConnectorEffect[];
+    });
+    // Only MAIN-path emits drive the drain re-check: they arm a fence, so
+    // the follow-up pass skips them and the job converges. Fork-owned
+    // outputs (spawnChildSession / deliverTo emits) never write a fence —
+    // counting them would re-check forever, and their fast re-plan would
+    // race the fork verification cadence — their loss recovery belongs to
+    // the fork machinery (parked acks, retry timer), not this job.
+    if (out.some((e) => e.type === 'emitEvent' && !e.deliverTo)) {
+      dirty = true;
+    }
+    effects.push(...out);
+    processed++;
+  }
+
+  if (processed < rows.length) {
+    // Soft budget hit mid-page: keep the cursor (the refetch re-lists this
+    // page; already-emitted rows fence-skip) and continue immediately. The
+    // failure streak is NOT reset mid-pass — only a failure-free pass end
+    // clears it, or a persistent 5xx in a multi-page backlog would compute
+    // a streak of 1 forever and rescan at the base delay instead of backing
+    // off. The re-arm timer leads the effect list: v2 replays effects in
+    // order and a dead-lettered earlier effect must not also cost the job
+    // its progression timer (setTimer is host-owned/idempotent — order is
+    // free on v1).
+    // Progress this round → no backoff: clear notBefore so a lingering value
+    // from an earlier failed round can't make a defer honour a stale backoff.
+    await writeState(ctx, { ...state, dirty, sawFailure, notBefore: 0 });
+    return [armCatchUpEffect(ctx), ...effects];
+  }
+  if (body.next_cursor) {
+    await writeState(ctx, { ...state, cursor: body.next_cursor, dirty, sawFailure, notBefore: 0 });
+    return [armCatchUpEffect(ctx), ...effects];
+  }
+
+  // Pass complete. Clean pass (nothing emitted, nothing failed) ends the job;
+  // a dirty pass runs another full pass from the top — the re-check that
+  // makes the cursor an optimization instead of a correctness source.
+  if (!dirty) {
+    await clearState(ctx);
+    return effects;
+  }
+  const failures = sawFailure ? state.failures + 1 : 0;
+  const delay = sawFailure ? backoffDelay(failures) : 0;
+  await writeState(ctx, {
+    ...FRESH_STATE,
+    phase: 'sweep',
+    failures,
+    notBefore: delay > 0 ? ctx.now() + delay : 0,
+  });
+  return [armCatchUpEffect(ctx, delay), ...effects];
+}

package/src/connect.ts

@@ -14,11 +14,13 @@ export async function connectParall(ctx: ConnectorContext): Promise<ConnectReque
   const apiUrl = parallApiUrl(ctx);
   const agk = requireAgk(ctx);
   // connect() runs on every (re)connect — fail fast rather than hang the host's
-  // reconnect loop on a wedged ticket endpoint.
+  // reconnect loop on a wedged ticket endpoint. 5s: the v2 connect budget is
+  // 15s and first-timeout rotates the epoch, so the single mint fetch must
+  // leave ample margin (session.ts REQUEST_TIMEOUT_MS rationale).
   const res = await fetch(`${apiUrl}/api/v1/ws/ticket`, {
     method: 'POST',
     headers: { Authorization: `Bearer ${agk}` },
-    signal: AbortSignal.timeout(10_000),
+    signal: AbortSignal.timeout(5_000),
   });
   if (!res.ok) {
     throw new Error(`parel-channel: ws ticket failed (${res.status})`);

package/src/fork.ts

@@ -59,7 +59,8 @@ const MAX_ACK_ATTEMPTS = 3;
 
 const MAIN_TURN_KEY = 'forkMainTurn';
 export const FORK_RETRY_PREFIX = 'forkRetry:';
-const FORK_DISABLED_KEY = 'forkDisabled';
+/** Exported for the catch-up job's reconnect revalidation (catchup.ts). */
+export const FORK_DISABLED_KEY = 'forkDisabled';
 const childKey = (subject: string) => `forkChild:${subject}`;
 const childSubjectKey = (childRef: string) => `forkChildSubject:${childRef}`;
 
@@ -249,6 +250,11 @@ export async function clearForkSubject(
 /**
  * Bump-and-park a fork retry ledger row (also the spawn-verification
  * coordinate onTimer re-plans). Returns the attempt count INCLUDING this one.
+ * Attempts count VERIFICATION ROUNDS on the retry timer's cadence, so a bump
+ * younger than FORK_RETRY_DELAY_MS is a fast replay (catch-up re-check pass,
+ * rapid reconnect double-sweep) and keeps the prior count — without the
+ * floor, back-to-back replays would burn through MAX_SPAWN_VERIFY_ATTEMPTS
+ * in milliseconds and black-hole a child that was starting up fine.
  */
 export async function bumpForkRetryAttempts(
   ctx: ConnectorContext,
@@ -257,9 +263,18 @@ export async function bumpForkRetryAttempts(
 ): Promise<number> {
   const prior = (await ctx.store?.get(retryKey).catch(() => null)) as {
     attempts?: number;
+    at?: number;
   } | null;
+  const now = ctx.now();
+  if (
+    typeof prior?.attempts === 'number' &&
+    typeof prior.at === 'number' &&
+    now - prior.at < FORK_RETRY_DELAY_MS
+  ) {
+    return prior.attempts;
+  }
   const attempts = (prior?.attempts ?? 0) + 1;
-  await ctx.store?.set(retryKey, { ...data, attempts }).catch(() => {});
+  await ctx.store?.set(retryKey, { ...data, attempts, at: now }).catch(() => {});
   return attempts;
 }
 

package/src/inbound-channel.ts

@@ -64,7 +64,10 @@ export async function effectsForChannelDispatch(
       // takes) — permanently unusable, drop it.
       return [completeSourceEffect(ctx, 'channel_message', sourceId)];
     }
-    return []; // transient: keep pending, the catch-up sweep retries
+    // Transient: keep pending — THROW so the catch-up job counts the row as
+    // starving and re-arms with backoff (transient-vs-deliberate contract,
+    // see inbound.ts message path).
+    throw new Error(`transient channel message fetch failure (${m.status})`);
   }
   const msg = (await m.json().catch(() => null)) as {
     conversation_id?: string;
@@ -92,7 +95,7 @@ export async function effectsForChannelDispatch(
     if (c.status === 404 || c.status === 403) {
       return [completeSourceEffect(ctx, 'channel_message', sourceId)];
     }
-    return [];
+    throw new Error(`transient channel conversation fetch failure (${c.status})`);
   }
   const conv = (await c.json().catch(() => null)) as {
     connection_id?: string;
@@ -118,6 +121,7 @@ export async function effectsForChannelDispatch(
   const receivedSettled = claimDispatchSource(ctx, 'channel_message', sourceId);
   const priorEmit = await readActiveEmit(ctx, 'channel_message', sourceId);
   const envelopeId = nextEnvelopeId('channel_message', sourceId, priorEmit);
+  let mappingEffect: ConnectorEffect | null = null;
   let sessionId = await ensureSession(ctx);
   if (sessionId) {
     await ctx.store?.set(TURN_ENVELOPE_KEY, envelopeId).catch(() => {});
@@ -137,23 +141,40 @@ export async function effectsForChannelDispatch(
       ]);
     const results = await report(sessionId);
     if (results.includes('stale')) {
+      // Same stale-repair contract as the chat path — and the same
+      // attribution rule: never leave sessionId pointing at the closed
+      // session (it feeds the fence below).
       await invalidateSession(ctx);
+      sessionId = null;
       const fresh = await ensureSession(ctx);
-      if (fresh && fresh !== sessionId) {
-        await report(fresh);
-        sessionId = fresh;
+      if (fresh) {
+        const retry = await report(fresh);
+        if (!retry.includes('stale')) 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(() => {});
+    // conversation into its session; last-write-wins on the server) as a
+    // FETCH EFFECT: host-executed, so it costs the hook budget nothing on
+    // the v1 host (a stalled PATCH awaited in-hook could blow the 5s budget
+    // and cost the emit), and the v2 outbox replays it with the idempotency
+    // key. The memo is written up front (inside the capture window): a
+    // dropped effect leaves the mapping stale until the session id next
+    // rotates — acceptable for an ops-observability pointer. Skipped when
+    // the stale repair above dropped the session — the next message records
+    // the fresh one.
+    if (sessionId) {
+      const mappedKey = `convSession:${conversationId}`;
+      const mapped = await ctx.store?.get(mappedKey).catch(() => null);
+      if (mapped !== sessionId) {
+        await ctx.store?.set(mappedKey, sessionId).catch(() => {});
+        mappingEffect = conversationSessionEffect(ctx, conversationId, sessionId);
+      }
+    }
   }
   await receivedSettled;
-  await writeActiveEmit(ctx, 'channel_message', sourceId, envelopeId);
+  // Fence carries this attempt's session for turn-end attribution (see
+  // ActiveEmit) — same contract as the chat-message path.
+  await writeActiveEmit(ctx, 'channel_message', sourceId, envelopeId, sessionId ?? undefined);
 
   // Live capability grant → this turn's lark-cli auth env (mint gate = the
   // no-drift revocation point) + the hint teaching the single reply path.
@@ -208,9 +229,35 @@ export async function effectsForChannelDispatch(
     },
     // No ack effect — see the message path (inbound.ts): the row stays
     // received until complete-sources closes it.
+    ...(mappingEffect ? [mappingEffect] : []),
   ];
 }
 
+/**
+ * The chv_ → ase_ mapping push as a host-executed fetch effect (idempotent
+ * last-write-wins PATCH; the key dedupes v2 outbox replays of this exact
+ * pairing).
+ */
+function conversationSessionEffect(
+  ctx: ConnectorContext,
+  conversationId: string,
+  sessionId: string,
+): Extract<ConnectorEffect, { type: 'fetch' }> {
+  return {
+    type: 'fetch',
+    request: {
+      url: `${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 }),
+    },
+    idempotencyKey: `convmap:${conversationId}:${sessionId}`,
+  };
+}
+
 /**
  * connection id → provider alias, cached in the durable store (stable
  * mapping; avoids one connection fetch per inbound message). Cache hits are
@@ -236,35 +283,3 @@ async function resolveChannelProvider(
     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);
-  }
-}