@parall/parel-channel 1.37.0

package/src/delivery.ts

@@ -0,0 +1,144 @@
+import type { ChannelDelivery, ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
+import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
+import {
+  ensureSession,
+  invalidateSession,
+  patchSession,
+  REQUEST_TIMEOUT_MS,
+  turnEnvelopeKey,
+} from './session.js';
+
+/**
+ * Post the agent's reply back to the Parall chat. The chat id rides the
+ * replyRoute.data set in inbound.ts.
+ *
+ * Contract (confirmed against parel #104): provider_http reply routes are
+ * auto-delivered at turn end via this hook; `payload` is the plain reply text
+ * string and `replyRoute` is the one captured from the originating envelope.
+ *
+ * The reply POST is awaited (not returned as a host fetch effect) so the
+ * session link resolution and failure handling stay in one place; a
+ * retryable failure falls back to the host effect (at-least-once, idempotent
+ * by delivery id + message idempotency_key). The turn's PRIMARY done signal
+ * lives in onAgentEvent (turn_completed); the idle here is a deliberate
+ * redundant close for bindings without `observe: [turn]` — see the inline
+ * comment at the bottom.
+ *
+ * External IM turns (channel_message dispatches) route here too but deliver
+ * NOTHING: their replyRoute carries a conversationId and no chatId, and the
+ * agent replies through the provider clip itself — this hook only runs the
+ * same redundant session idle for them.
+ */
+export async function buildParallDelivery(
+  delivery: ChannelDelivery,
+  ctx: ConnectorContext,
+): Promise<ConnectorEffect[]> {
+  const apiUrl = parallApiUrl(ctx);
+  const agk = requireAgk(ctx);
+  const orgId = parallOrgId(ctx);
+  const route = (delivery.replyRoute?.data ?? {}) as {
+    chatId?: string;
+    messageId?: string;
+    threadRootId?: string;
+    envelopeId?: string;
+    conversationId?: string;
+  };
+  const chatId = route.chatId;
+  if (!chatId) {
+    // External IM turn (channel_message): the reply already went out through
+    // the provider clip, agent-invoked — the turn-end text is deliberately
+    // NOT delivered anywhere (same contract as agent-core: plain output is
+    // not the reply). Only run the redundant idle so a binding without
+    // `observe: [turn]` still closes the session.
+    if (route.conversationId) {
+      const sessionId = await ensureSession(ctx, route.conversationId, { timeoutMs: 3_000 });
+      if (sessionId) {
+        await idleUnlessSuperseded(ctx, route.conversationId, route.envelopeId, sessionId);
+      }
+    }
+    return [];
+  }
+
+  const payload = delivery.payload as { text?: string } | string | undefined;
+  const text = typeof payload === 'string' ? payload : (payload?.text ?? '');
+  if (!text) return [];
+
+  // Short timeout: this sits in front of the user-visible reply POST. Cache
+  // hit (every message after a chat's first) is a store read; on a slow miss
+  // we degrade to a reply without the session link rather than delay it.
+  const sessionId = await ensureSession(ctx, chatId, { timeoutMs: 3_000 });
+
+  const request = {
+    url: `${apiUrl}/api/v1/orgs/${orgId}/chats/${chatId}/messages`,
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${agk}`,
+      'Content-Type': 'application/json',
+    },
+    // message_type must be explicit: the server persists it verbatim, and
+    // a blank type skips text normalization (prll:// refs, mentions) and
+    // renders as an unknown-type fallback on clients. agent_session_id links
+    // the reply bubble to its session panel (server validates ownership).
+    // idempotency_key dedupes the ambiguous-failure case where the direct
+    // POST committed but its response was lost and the host retry re-sends —
+    // same body on both paths, so the server collapses them to one message.
+    body: JSON.stringify({
+      message_type: 'text',
+      content: { text },
+      idempotency_key: `parel-reply:${delivery.id}`,
+      // A reply to a thread message stays in that thread.
+      ...(route.threadRootId ? { thread_root_id: route.threadRootId } : {}),
+      ...(sessionId ? { agent_session_id: sessionId } : {}),
+    }),
+  };
+
+  try {
+    const res = await fetch(request.url, {
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      // 4xx (bar 429) is permanent — retrying an unprocessable reply burns
+      // requests forever. Drop it (logged); turn_completed still closes the
+      // turn's indicator.
+      const permanent = res.status >= 400 && res.status < 500 && res.status !== 429;
+      if (!permanent) throw new Error(`reply post failed (${res.status})`);
+      console.error(`[parel-channel] reply rejected (${res.status}) — dropping`);
+    }
+  } catch (err) {
+    console.error('[parel-channel] direct reply failed; falling back to host retry', err);
+    return [{ type: 'fetch', request, idempotencyKey: `reply:${delivery.id}` }];
+  }
+
+  // Redundant done signal, kept deliberately: turn_completed (onAgentEvent)
+  // is the primary close for every turn — including no-reply turns this hook
+  // never sees — but a binding deployed without `observe: [turn]` that still
+  // resolves this connector (npm ^1 fallback path; the artifact path freezes
+  // connector+config atomically) would otherwise never idle. Both signals
+  // run the same turnEnvelope staleness guard and idle is idempotent, so the
+  // overlap is harmless.
+  if (sessionId) {
+    await idleUnlessSuperseded(ctx, chatId, route.envelopeId, sessionId);
+  }
+  return [];
+}
+
+/**
+ * Idle the subject's session unless a newer envelope owns the turn (the same
+ * turnEnvelope staleness guard onAgentEvent runs). Fail-open when the marker
+ * is unavailable — a stuck ring is worse than a blink.
+ */
+async function idleUnlessSuperseded(
+  ctx: ConnectorContext,
+  subject: string,
+  envelopeId: string | undefined,
+  sessionId: string,
+): Promise<void> {
+  const current = await ctx.store?.get(turnEnvelopeKey(subject)).catch(() => null);
+  if (!(typeof current === 'string' && current) || !envelopeId || current === envelopeId) {
+    const result = await patchSession(ctx, sessionId, { status: 'idle' });
+    if (result === 'stale') await invalidateSession(ctx, subject);
+  }
+}