@parall/parel-channel 1.37.0

package/src/inbound.ts

@@ -0,0 +1,623 @@
+import type {
+  AgentEvent,
+  AgentEventEffect,
+  ConnectorContext,
+  ConnectorEffect,
+  WebSocketFrame,
+} from '@parel/plugin-sdk';
+import { buildChannelPrompt } from './channel-prompt.js';
+import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
+import {
+  createChannelInputStep,
+  createInputStep,
+  createTraceStep,
+  ensureSession,
+  invalidateSession,
+  markDispatchReceived,
+  patchSession,
+  REQUEST_TIMEOUT_MS,
+  turnEnvelopeKey,
+} from './session.js';
+
+/**
+ * Inbound path: Parall dispatches → agent.
+ *
+ * The Parall gateway pushes `dispatch.new` signals on the agent's WS; the
+ * dispatch is a pointer (source_type/source_id), not the payload. For each
+ * message dispatch we pull the source message text, emit it to the agent as a
+ * ChannelEnvelope, and ack the dispatch by source so it isn't redelivered.
+ * On (re)connect, onOpen sweeps `GET /dispatch` so dispatches that arrived
+ * while the socket was down are not lost — the WS push has no replay.
+ *
+ * Contract (confirmed against parel #102–#107): raw WS frames are handed to
+ * onMessage verbatim; the binding created by the agent.yaml `channels:` block
+ * routes emitted envelopes to this agent, keyed by `subject` under
+ * `routing: {mode: per_subject}`; ack-on-emit matches channel-slack-socket.
+ *
+ * Scope: `source_type === "message"` dispatches (DMs and mentions) and
+ * `source_type === "channel_message"` dispatches (external IM — Feishu/Slack
+ * via the platform-mediated channel, keyed by their ChannelConversation) are
+ * emitted. Task/schedule/trigger dispatches stay pending rather than being
+ * acked-and-dropped.
+ */
+
+interface DispatchData {
+  id?: unknown;
+  source_type?: unknown;
+  source_id?: unknown;
+  chat_id?: unknown;
+}
+
+export async function handleParallFrame(
+  frame: WebSocketFrame,
+  ctx: ConnectorContext,
+): Promise<ConnectorEffect[]> {
+  let event: { type?: string; data?: DispatchData };
+  try {
+    const raw = typeof frame.data === 'string' ? frame.data : new TextDecoder().decode(frame.data);
+    event = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (event.type !== 'dispatch.new' || !event.data) return [];
+  try {
+    return await effectsForDispatch(event.data, ctx);
+  } catch (err) {
+    // A transient fetch failure on one frame must not fail the frame handler —
+    // the dispatch stays pending and the onOpen sweep replays it on reconnect.
+    console.error('[parel-channel] dispatch handling failed', err);
+    return [];
+  }
+}
+
+/**
+ * Sweep pending dispatches on (re)connect — the live WS push has no replay.
+ * Paginates with the server cursor so a long outage's backlog is not silently
+ * truncated (bounded to keep a pathological backlog from wedging onOpen; the
+ * remainder is picked up on the next reconnect sweep).
+ */
+export async function catchUpParall(ctx: ConnectorContext): Promise<ConnectorEffect[]> {
+  const effects: ConnectorEffect[] = [];
+  try {
+    const apiUrl = parallApiUrl(ctx);
+    const agk = requireAgk(ctx);
+    const orgId = parallOrgId(ctx);
+    let cursor = '';
+    // Page bound is a wedge guard, not a coverage target. Non-message
+    // dispatches stay pending (deliberately — see effectsForDispatch) and the
+    // 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
+    // pathological backlog is visible instead of silent.
+    const maxPages = 40;
+    let page = 0;
+    for (; page < maxPages; page++) {
+      const url = `${apiUrl}/api/v1/orgs/${orgId}/dispatch?limit=50${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''}`;
+      const res = await fetch(url, {
+        headers: { Authorization: `Bearer ${agk}` },
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (!res.ok) break;
+      const body = (await res.json().catch(() => null)) as {
+        data?: DispatchData[];
+        next_cursor?: string;
+      } | null;
+      // Same-chat dispatches run SEQUENTIALLY (session reporting PATCHes one
+      // shared session per chat — concurrent replay would let an older
+      // dispatch overwrite trigger_message_id after a newer one and reorder
+      // input steps); different chats still run concurrently. Page order is
+      // FIFO, so per-chat envelope order is preserved. A failed dispatch
+      // resolves to [] and stays pending for the next sweep.
+      //
+      // channel_message dispatches carry no chat_id and their conversation
+      // (the session key) is only known after fetching the message — so they
+      // all share ONE sequential chain: per-conversation order is preserved
+      // at the cost of serializing across conversations, which is fine for
+      // the small external-IM backlogs a reconnect sweep sees.
+      const byChat = new Map<string, DispatchData[]>();
+      const unkeyed: DispatchData[] = [];
+      for (const d of body?.data ?? []) {
+        const cid =
+          String(d.source_type ?? '') === 'channel_message'
+            ? CHANNEL_SWEEP_CHAIN
+            : d.chat_id
+              ? String(d.chat_id)
+              : '';
+        if (!cid) {
+          unkeyed.push(d);
+          continue;
+        }
+        const group = byChat.get(cid);
+        if (group) group.push(d);
+        else byChat.set(cid, [d]);
+      }
+      const runOne = (d: DispatchData) =>
+        effectsForDispatch(d, ctx).catch((err) => {
+          console.error('[parel-channel] catch-up dispatch failed', err);
+          return [] as ConnectorEffect[];
+        });
+      const chains = [...byChat.values()].map(async (group) => {
+        const out: ConnectorEffect[] = [];
+        for (const d of group) out.push(...(await runOne(d)));
+        return out;
+      });
+      const pageEffects = await Promise.all([...chains, ...unkeyed.map(runOne)]);
+      effects.push(...pageEffects.flat());
+      if (!body?.next_cursor) break;
+      cursor = body.next_cursor;
+    }
+    if (page === maxPages) {
+      console.warn(
+        '[parel-channel] catch-up hit the page ceiling; remainder deferred to the next reconnect sweep',
+      );
+    }
+  } catch (err) {
+    // Catch-up is best-effort: keep whatever pages completed and never fail
+    // the connection open over it.
+    console.error('[parel-channel] dispatch catch-up failed', err);
+  }
+  return effects;
+}
+
+/**
+ * Synthetic sweep group key for channel_message dispatches (no chat_id).
+ * Chat ids are cht_-prefixed nanoids, so this cannot collide with one.
+ */
+const CHANNEL_SWEEP_CHAIN = 'sweep:channel_message';
+
+async function effectsForDispatch(
+  data: DispatchData,
+  ctx: ConnectorContext,
+): Promise<ConnectorEffect[]> {
+  const sourceType = String(data.source_type ?? '');
+  const sourceId = data.source_id ? String(data.source_id) : undefined;
+  const chatId = data.chat_id ? String(data.chat_id) : undefined;
+  const dispatchId = String(data.id ?? '');
+  if (sourceType === 'channel_message' && sourceId) {
+    // External IM message (chat_id is NULL by design — the conversation
+    // 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.
+  if (sourceType !== 'message' || !sourceId) return [];
+  if (!chatId) {
+    // A message dispatch with no chat can never be routed or replied to.
+    return [ackEffect(ctx, sourceType, sourceId)];
+  }
+
+  const apiUrl = parallApiUrl(ctx);
+  const agk = requireAgk(ctx);
+  const orgId = parallOrgId(ctx);
+
+  // Pull the source message text (global by-id read; ACL = chat membership).
+  const m = await fetch(`${apiUrl}/api/v1/messages/${sourceId}`, {
+    headers: { Authorization: `Bearer ${agk}` },
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!m.ok) {
+    if (m.status === 404 || m.status === 403) {
+      // Deleted message / lost chat access — permanently unusable, drop it.
+      return [ackEffect(ctx, sourceType, sourceId)];
+    }
+    // Transient failure: keep pending, the catch-up sweep retries.
+    return [];
+  }
+  const msg = (await m.json().catch(() => null)) as {
+    content?: { text?: string };
+    thread_root_id?: string;
+    sender_id?: string;
+  } | null;
+  const text = msg?.content?.text ?? '';
+  // A thread reply anchors the agent's answer to the same thread.
+  const threadRootId = msg?.thread_root_id || undefined;
+  if (!text) {
+    // Attachment-only / empty-text messages never grow text — MVP has no
+    // attachment path, so ack-and-drop rather than let them pile up in the
+    // pending queue forever.
+    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);
+  const envelopeId = dispatchId || `${sourceType}:${sourceId}`;
+  let sessionId = await ensureSession(ctx, chatId);
+  if (sessionId) {
+    // The guard marker goes down BEFORE any session write: a stale
+    // turn_completed for the PREVIOUS turn (outbox retry, late event) checks
+    // turnEnvelope to decide whether its idle is still safe — if the active
+    // patch below could land first, that event would still see the old
+    // envelope id and idle the session out from under this message.
+    // (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(turnEnvelopeKey(chatId), envelopeId).catch(() => {});
+    const report = (sid: string) =>
+      Promise.all([
+        patchSession(ctx, sid, { status: 'active', trigger_message_id: sourceId }),
+        createInputStep(ctx, sid, {
+          chatId,
+          messageId: sourceId,
+          senderId: msg?.sender_id ? String(msg.sender_id) : undefined,
+          text,
+        }),
+      ]);
+    const results = await report(sessionId);
+    if (results.includes('stale')) {
+      // The cached session was closed under us (e.g. New Session). The
+      // get-or-create falls through terminal rows, so one rebuild + retry
+      // repairs reporting for this and every later dispatch.
+      await invalidateSession(ctx, chatId);
+      const fresh = await ensureSession(ctx, chatId);
+      if (fresh && fresh !== sessionId) {
+        await report(fresh);
+        sessionId = fresh;
+      }
+    }
+  }
+  await receivedSettled;
+
+  // Per-turn invocation context: parel snapshots this at turn start and
+  // consume-gated plugins receive it — sandbox-e2b flattens it into per-exec
+  // env, so `parall` CLI calls inside the sandbox land on the right chat.
+  const invocationContext: Record<string, string> = {
+    PRLL_CHAT_ID: chatId,
+    PRLL_TRIGGER_MESSAGE_ID: sourceId,
+    ...(threadRootId ? { PRLL_THREAD_ROOT_ID: threadRootId } : {}),
+  };
+
+  const effects: ConnectorEffect[] = [
+    {
+      type: 'emitEvent',
+      event: {
+        id: envelopeId,
+        orgId,
+        connectionId: ctx.connectionId,
+        source: 'parall',
+        type: 'message',
+        // per_subject routing keys the parel session by subject → one parel
+        // session per Parall chat (mirrors Parall's chat-scoped conversations).
+        subject: chatId,
+        data: { text, 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;
+}
+
+/**
+ * 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.
+ */
+async function effectsForChannelDispatch(
+  sourceId: string,
+  dispatchId: string,
+  ctx: ConnectorContext,
+): Promise<ConnectorEffect[]> {
+  const apiUrl = parallApiUrl(ctx);
+  const orgId = parallOrgId(ctx);
+  const authHeaders = { Authorization: `Bearer ${requireAgk(ctx)}` };
+  const get = (path: string, timeoutMs: number = REQUEST_TIMEOUT_MS) =>
+    fetch(`${apiUrl}/api/v1/orgs/${orgId}${path}`, {
+      headers: authHeaders,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+
+  const m = await get(`/channel-messages/${sourceId}`);
+  if (!m.ok) {
+    if (m.status === 404 || m.status === 403) {
+      // Deleted / inaccessible (also the shape a disabled org feature flag
+      // takes) — permanently unusable, drop it.
+      return [ackEffect(ctx, 'channel_message', sourceId)];
+    }
+    return []; // transient: keep pending, the catch-up sweep retries
+  }
+  const msg = (await m.json().catch(() => null)) as {
+    conversation_id?: string;
+    external_message_id?: string;
+    text?: string;
+    external_user_id?: string;
+    external_user_name?: string;
+    received_at?: string;
+  } | null;
+  const conversationId = msg?.conversation_id ? String(msg.conversation_id) : undefined;
+  const text = msg?.text ?? '';
+  if (!conversationId) {
+    // No conversation → no session key and no reply target: unusable.
+    return [ackEffect(ctx, 'channel_message', sourceId)];
+  }
+  if (!text) {
+    // The ingress adapter only persists mechanically parsed text; a row with
+    // none will never grow any (same reasoning as attachment-only chat
+    // messages) — drop rather than let it pile up in the pending queue.
+    return [ackEffect(ctx, 'channel_message', sourceId)];
+  }
+
+  const c = await get(`/channel-conversations/${conversationId}`);
+  if (!c.ok) {
+    if (c.status === 404 || c.status === 403) {
+      return [ackEffect(ctx, 'channel_message', sourceId)];
+    }
+    return [];
+  }
+  const conv = (await c.json().catch(() => null)) as {
+    connection_id?: string;
+    external_conversation_id?: string;
+    conversation_type?: string;
+  } | null;
+
+  // Provider (= clip alias) for prompt labeling + the reply hint.
+  // Best-effort: an unresolved provider degrades the wording, never blocks.
+  const connectionId = conv?.connection_id ? String(conv.connection_id) : undefined;
+  const provider = connectionId ? await resolveChannelProvider(ctx, connectionId, get) : undefined;
+
+  const senderName = msg?.external_user_name || msg?.external_user_id || 'external user';
+  const externalConversationId = conv?.external_conversation_id
+    ? String(conv.external_conversation_id)
+    : undefined;
+  const externalMessageId = msg?.external_message_id ? String(msg.external_message_id) : undefined;
+
+  // Progress reporting — identical ordering contract to the message path
+  // (see the comments there): received settles before the ack effect is
+  // returned; the turnEnvelope marker goes down before any session write.
+  const receivedSettled = markDispatchReceived(ctx, 'channel_message', sourceId);
+  const envelopeId = dispatchId || `channel_message:${sourceId}`;
+  let sessionId = await ensureSession(ctx, conversationId);
+  if (sessionId) {
+    await ctx.store?.set(turnEnvelopeKey(conversationId), envelopeId).catch(() => {});
+    const report = (sid: string) =>
+      Promise.all([
+        patchSession(ctx, sid, { status: 'active', trigger_message_id: sourceId }),
+        createChannelInputStep(ctx, sid, {
+          conversationId,
+          channelMessageId: sourceId,
+          provider,
+          externalConversationId,
+          senderId: msg?.external_user_id ? String(msg.external_user_id) : 'external',
+          senderName,
+          text,
+          sentAt: msg?.received_at ? String(msg.received_at) : undefined,
+        }),
+      ]);
+    const results = await report(sessionId);
+    if (results.includes('stale')) {
+      await invalidateSession(ctx, conversationId);
+      const fresh = await ensureSession(ctx, conversationId);
+      if (fresh && fresh !== sessionId) {
+        await report(fresh);
+        sessionId = fresh;
+      }
+    }
+    // Record the durable chv_ ↔ ase_ mapping (ops drill-down from a
+    // conversation into its session; last-write-wins on the server). Only on
+    // change — the store remembers what was last pushed — and fully
+    // fire-and-forget: pure bookkeeping must never add latency to the
+    // emit/ack path (a lost attempt is retried on the next message because
+    // the store memo only updates on success).
+    void recordConversationSession(ctx, conversationId, sessionId).catch(() => {});
+  }
+  await receivedSettled;
+
+  return [
+    {
+      type: 'emitEvent',
+      event: {
+        id: envelopeId,
+        orgId,
+        connectionId: ctx.connectionId,
+        source: 'parall',
+        // The host's message intake path turns data.text into the user
+        // message — the external-audience framing rides inside it (parel has
+        // no separate prompt channel), so 'message' is the right type here.
+        type: 'message',
+        // per_subject routing keys the parel session by subject → one parel
+        // session per external conversation (mirrors chv_ ↔ session 1:1 in
+        // the design).
+        subject: conversationId,
+        data: {
+          text: buildChannelPrompt({
+            provider,
+            conversationType: conv?.conversation_type ? String(conv.conversation_type) : undefined,
+            externalConversationId,
+            externalMessageId,
+            senderName,
+            text,
+          }),
+          conversationId,
+          channelMessageId: sourceId,
+          provider,
+          externalConversationId,
+          externalMessageId,
+        },
+        // No chatId on purpose: the reply goes out through the provider clip
+        // (agent-invoked), NOT deliver() — deliver only runs the redundant
+        // session idle for channel routes (see delivery.ts).
+        replyRoute: {
+          kind: 'provider_http',
+          connectionId: ctx.connectionId,
+          data: { conversationId, envelopeId },
+        },
+        // No invocation context: PRLL_CHAT_ID must not point CLI defaults at
+        // a chat that doesn't exist, and the reply targets (external ids)
+        // already ride the prompt verbatim.
+      },
+    },
+    ackEffect(ctx, 'channel_message', sourceId),
+  ];
+}
+
+/**
+ * connection id → provider alias, cached in the durable store (stable
+ * mapping; avoids one connection fetch per inbound message). Cache hits are
+ * a store read; 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;
+
+async function resolveChannelProvider(
+  ctx: ConnectorContext,
+  connectionId: string,
+  get: (path: string, timeoutMs?: number) => Promise<Response>,
+): Promise<string | undefined> {
+  const cacheKey = `channelProvider:${connectionId}`;
+  const cached = await ctx.store?.get(cacheKey).catch(() => null);
+  if (typeof cached === 'string' && cached) return cached;
+  try {
+    const res = await get(`/channel-connections/${connectionId}`, PROVIDER_LOOKUP_TIMEOUT_MS);
+    if (!res.ok) return undefined;
+    const body = (await res.json().catch(() => null)) as { provider?: string } | null;
+    const provider = body?.provider ? String(body.provider) : undefined;
+    if (provider) await ctx.store?.set(cacheKey, provider).catch(() => {});
+    return provider;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Push the chv_ → ase_ pointer when it changed; warn-only on failure. */
+async function recordConversationSession(
+  ctx: ConnectorContext,
+  conversationId: string,
+  sessionId: string,
+): Promise<void> {
+  const mappedKey = `convSession:${conversationId}`;
+  const mapped = await ctx.store?.get(mappedKey).catch(() => null);
+  if (mapped === sessionId) return;
+  try {
+    const res = await fetch(
+      `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/channel-conversations/${conversationId}/session`,
+      {
+        method: 'PATCH',
+        headers: {
+          Authorization: `Bearer ${requireAgk(ctx)}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ agent_session_id: sessionId }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      },
+    );
+    if (!res.ok) {
+      console.warn(`[parel-channel] conversation session mapping failed (${res.status})`);
+      return;
+    }
+    await ctx.store?.set(mappedKey, sessionId).catch(() => {});
+  } catch (err) {
+    console.warn('[parel-channel] conversation session mapping failed', err);
+  }
+}
+
+/**
+ * Agent execution events (parel E1+E2, plugin-sdk 0.9.0, opt-in via the
+ * channel declaration's `observe: [turn, steps]`).
+ *
+ * E1 (turn lifecycle): turn_completed fires unconditionally on every cleanly
+ * finished turn — INCLUDING no-reply turns (hadOutput: false), the reliable
+ * "processing ended" signal that used to need a 30min turnwatch timer.
+ * turn_failed closes the turn the same way.
+ *
+ * E2 (step trace): model_reasoning / tool_call / tool_result become parall
+ * AgentSteps — the session panel gets the same live execution feed CC agents
+ * have (reasoning is aggregated host-side; tool output is a bounded preview).
+ *
+ * Events are best-effort (display feed, never data-correctness): a missed
+ * 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: AgentEvent,
+  ctx: ConnectorContext,
+): Promise<AgentEventEffect[]> {
+  const chatId = event.subject;
+  if (!chatId) return [];
+  try {
+    if (event.type === 'turn_completed' || event.type === 'turn_failed') {
+      // Staleness guard: only idle if this event's turn is still the chat's
+      // latest emitted envelope — a late/retried completed event for a
+      // superseded turn must not clear the newer turn's indicator. Fail-open
+      // when the marker is unavailable (a stuck ring is worse than a blink).
+      const current = await ctx.store?.get(turnEnvelopeKey(chatId)).catch(() => null);
+      if (typeof current === 'string' && current && !event.envelopeIds.includes(current)) {
+        return [];
+      }
+      const sessionId = await ensureSession(ctx, chatId);
+      if (sessionId) {
+        const result = await patchSession(ctx, sessionId, { status: 'idle' });
+        // A closed session is already terminal (frontend shows done) — just
+        // drop the cache so the next dispatch resolves a fresh one.
+        if (result === 'stale') await invalidateSession(ctx, chatId);
+      }
+      return [];
+    }
+    if (
+      event.type === 'model_reasoning' ||
+      event.type === 'tool_call' ||
+      event.type === 'tool_result'
+    ) {
+      const sessionId = await ensureSession(ctx, chatId);
+      if (sessionId) {
+        const result = await createTraceStep(ctx, sessionId, chatId, event);
+        // Dropped step is fine (display feed); uncache so the NEXT event
+        // resolves a live session instead of failing forever.
+        if (result === 'stale') await invalidateSession(ctx, chatId);
+      }
+      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].
+  } catch (err) {
+    console.error('[parel-channel] agent event handling failed', err);
+  }
+  return [];
+}
+
+/** Ack a dispatch by source so it leaves the pending queue (idempotent). */
+function ackEffect(ctx: ConnectorContext, sourceType: string, sourceId: string): ConnectorEffect {
+  return {
+    type: 'fetch',
+    request: {
+      url: `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/dispatch/ack`,
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${requireAgk(ctx)}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ source_type: sourceType, source_id: sourceId }),
+    },
+    idempotencyKey: `ack:${sourceType}:${sourceId}`,
+  };
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+import type { ChannelConnector } from '@parel/plugin-sdk';
+import { connectParall } from './connect.js';
+import { buildParallDelivery } from './delivery.js';
+import { catchUpParall, handleParallAgentEvent, handleParallFrame } from './inbound.js';
+
+/**
+ * Parall channel plugin for the parel runtime.
+ *
+ * Lets a parel agent treat Parall as a `managed_ws` channel — mirroring what
+ * channel-slack-socket does for Slack. The parel runtime owns the connection
+ * lifecycle + agent routing; this connector just supplies the three hooks:
+ *
+ *   connect()   → the Parall gateway WS url (authenticated by the agent's agk_)
+ *   onMessage() → translate a Parall dispatch frame into a ChannelEnvelope
+ *   deliver()   → post the agent's reply back to the Parall chat via the API
+ *
+ * This is why Parall needs NO server-side worker/bridge: the integration lives
+ * here, runs inside parel, and is service-to-service from parel's side.
+ */
+const connector: ChannelConnector = {
+  connect: connectParall,
+  onOpen: catchUpParall,
+  onMessage: handleParallFrame,
+  onAgentEvent: handleParallAgentEvent,
+  deliver: buildParallDelivery,
+};
+
+export default connector;