@parall/parel-channel 1.40.0 → 1.42.0

package/src/inbound-channel.ts

@@ -0,0 +1,264 @@
+import type { ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
+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: 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 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: 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);
+      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: 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);
+  }
+}