@parall/parel-channel 1.37.0

package/src/session.ts

@@ -0,0 +1,333 @@
+import type { ConnectorContext } from '@parel/plugin-sdk';
+import { parallAgentId, parallApiUrl, parallOrgId, requireAgk } from './connect.js';
+
+/**
+ * Best-effort progress reporting: dispatch received, AgentSession lifecycle,
+ * and input steps — the signals parall's message-level activity indicator and
+ * session panel are built on (see parall-runtime-indicator-plan.md §3).
+ *
+ * Every function catches its own failures and returns a degraded value: the
+ * message pipeline (emit / reply) must never block on indicator reporting.
+ *
+ * Session identity is deterministic — (runtime_type='parel',
+ * runtime_session_id=subject), where the subject is the envelope routing key:
+ * a chat id (cht_) for Parall chats, or a channel conversation id (chv_) for
+ * external IM conversations. per_subject routing already keys one parel
+ * session per subject, so the parall-side session mirrors it 1:1 without the
+ * connector ever knowing parel's internal session id.
+ */
+
+export const REQUEST_TIMEOUT_MS = 10_000;
+
+/** Reporting needs the agent id in the endpoint path; old configs lack it. */
+export function reportingEnabled(ctx: ConnectorContext): boolean {
+  return parallAgentId(ctx) !== '';
+}
+
+/**
+ * The subject's most recently emitted envelope id — the staleness guard for
+ * turn-level done signals: a turn_completed/failed whose envelopeIds don't
+ * include the current value belongs to a superseded turn and must not idle
+ * the session out from under the newer one.
+ */
+export const turnEnvelopeKey = (subject: string) => `turnEnvelope:${subject}`;
+const sessionKey = (subject: string) => `session:${subject}`;
+
+/**
+ * 'stale' means the session id no longer accepts writes (closed/superseded —
+ * e.g. the New Session control ended it): callers invalidate the cache and
+ * may retry once against a fresh get-or-create, which falls through terminal
+ * rows and creates a new session server-side.
+ */
+export type ReportResult = 'ok' | 'stale' | 'failed';
+
+function resultForStatus(status: number): ReportResult {
+  return status === 404 || status === 409 || status === 410 ? 'stale' : 'failed';
+}
+
+/** Drop the cached session id so the next ensureSession re-resolves it. */
+export async function invalidateSession(ctx: ConnectorContext, subject: string): Promise<void> {
+  await ctx.store?.delete(sessionKey(subject)).catch(() => {});
+}
+
+function jsonHeaders(ctx: ConnectorContext): Record<string, string> {
+  return {
+    Authorization: `Bearer ${requireAgk(ctx)}`,
+    'Content-Type': 'application/json',
+  };
+}
+
+/**
+ * Get-or-create the subject's parall AgentSession (ase_), cached in the
+ * durable per-connection store. Returns null when reporting is disabled or
+ * the call fails — callers skip their report and move on. Callers on a
+ * latency-sensitive path (deliver blocks the user-visible reply on this) pass
+ * a shorter timeoutMs; the cache-hit fast path is a store read either way.
+ */
+export async function ensureSession(
+  ctx: ConnectorContext,
+  subject: string,
+  opts: { timeoutMs?: number } = {},
+): Promise<string | null> {
+  if (!reportingEnabled(ctx)) return null;
+  const cached = await ctx.store?.get(sessionKey(subject)).catch(() => null);
+  if (typeof cached === 'string' && cached) return cached;
+  try {
+    const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/agents/${parallAgentId(ctx)}/sessions`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: jsonHeaders(ctx),
+      body: JSON.stringify({ runtime_type: 'parel', runtime_session_id: subject }),
+      signal: AbortSignal.timeout(opts.timeoutMs ?? REQUEST_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      console.error(`[parel-channel] session get-or-create failed (${res.status})`);
+      return null;
+    }
+    const body = (await res.json().catch(() => null)) as { id?: string } | null;
+    const id = body?.id;
+    if (!id) return null;
+    await ctx.store?.set(sessionKey(subject), id).catch(() => {});
+    return id;
+  } catch (err) {
+    console.error('[parel-channel] session get-or-create failed', err);
+    return null;
+  }
+}
+
+/** PATCH the session (status / trigger_message_id). Never throws. */
+export async function patchSession(
+  ctx: ConnectorContext,
+  sessionId: string,
+  body: { status: 'active' | 'idle'; trigger_message_id?: string },
+): Promise<ReportResult> {
+  try {
+    const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/agents/${parallAgentId(ctx)}/sessions/${sessionId}`;
+    const res = await fetch(url, {
+      method: 'PATCH',
+      headers: jsonHeaders(ctx),
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (res.ok) return 'ok';
+    console.error(`[parel-channel] session patch failed (${res.status})`);
+    return resultForStatus(res.status);
+  } catch (err) {
+    console.error('[parel-channel] session patch failed', err);
+    return 'failed';
+  }
+}
+
+/**
+ * The input step is what flips the frontend indicator from pending to
+ * processing — target_type/target_id route the agent_step.new broadcast to
+ * messages:{chatId}, and content.trigger_ref.message_id is the exact match
+ * key (both mandatory; the server only publishes when a target is set).
+ */
+export async function createInputStep(
+  ctx: ConnectorContext,
+  sessionId: string,
+  args: { chatId: string; messageId: string; senderId?: string; text: string },
+): Promise<ReportResult> {
+  try {
+    const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/agents/${parallAgentId(ctx)}/sessions/${sessionId}/steps`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: jsonHeaders(ctx),
+      body: JSON.stringify({
+        step_type: 'input',
+        target_type: 'chat',
+        target_id: args.chatId,
+        // Session-scoped dedup: an ack failure leaves the dispatch replayable
+        // by the reconnect catch-up sweep — without this key every replay
+        // would insert and broadcast another input step for the same message.
+        idempotency_key: `input:${args.messageId}`,
+        content: {
+          trigger_type: 'mention',
+          trigger_ref: { message_id: args.messageId },
+          ...(args.senderId ? { sender_id: args.senderId } : {}),
+          summary: args.text.slice(0, 200),
+        },
+      }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (res.ok) return 'ok';
+    console.error(`[parel-channel] input step failed (${res.status})`);
+    return resultForStatus(res.status);
+  } catch (err) {
+    console.error('[parel-channel] input step failed', err);
+    return 'failed';
+  }
+}
+
+/**
+ * Input step for a channel_message dispatch (external IM). Shaped exactly
+ * like agent-core's channel input step so the session panel renders both
+ * runtimes identically: target = the ChannelConversation (chv_), trigger_ref
+ * carries the channel identifiers, and the sender is the external user
+ * (a display name, not a Parall usr_).
+ */
+export async function createChannelInputStep(
+  ctx: ConnectorContext,
+  sessionId: string,
+  args: {
+    conversationId: string;
+    channelMessageId: string;
+    provider?: string;
+    externalConversationId?: string;
+    senderId: string;
+    senderName: string;
+    text: string;
+    sentAt?: string;
+  },
+): Promise<ReportResult> {
+  try {
+    const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/agents/${parallAgentId(ctx)}/sessions/${sessionId}/steps`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: jsonHeaders(ctx),
+      body: JSON.stringify({
+        step_type: 'input',
+        target_type: 'channel_conversation',
+        target_id: args.conversationId,
+        // Session-scoped dedup, same rationale as the chat input step: a
+        // failed ack leaves the dispatch replayable by the catch-up sweep.
+        idempotency_key: `input:${args.channelMessageId}`,
+        content: {
+          trigger_type: 'channel_message',
+          trigger_ref: {
+            conversation_id: args.conversationId,
+            channel_message_id: args.channelMessageId,
+            ...(args.provider ? { provider: args.provider } : {}),
+            ...(args.externalConversationId
+              ? { external_conversation_id: args.externalConversationId }
+              : {}),
+          },
+          sender_id: args.senderId,
+          sender_name: args.senderName,
+          summary: args.text.slice(0, 200),
+          ...(args.sentAt ? { sent_at: args.sentAt } : {}),
+        },
+      }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (res.ok) return 'ok';
+    console.error(`[parel-channel] channel input step failed (${res.status})`);
+    return resultForStatus(res.status);
+  } catch (err) {
+    console.error('[parel-channel] channel input step failed', err);
+    return 'failed';
+  }
+}
+
+// Subject-scoped: one connector serves many per-subject sessions, and
+// provider call ids are only unique within a turn — never let two subjects'
+// concurrent calls overwrite each other's parked name.
+const toolNameKey = (subject: string, callId: string) => `toolName:${subject}:${callId}`;
+
+/**
+ * E2 step-trace events → parall AgentSteps, shaped exactly like agent-core's
+ * createRuntimeStep so the session panel renders them identically to CC's.
+ * tool_call/tool_result carry a session-scoped idempotency key (events are
+ * at-most-once today, but a callId key is free insurance); reasoning has no
+ * natural key and parel already aggregates it host-side. The E2 tool_result
+ * event has no tool name, so tool_call parks it in the store by callId.
+ */
+export async function createTraceStep(
+  ctx: ConnectorContext,
+  sessionId: string,
+  subject: string,
+  event:
+    | { type: 'model_reasoning'; text: string }
+    | { type: 'tool_call'; callId: string; name: string; input: unknown }
+    | {
+        type: 'tool_result';
+        callId: string;
+        status: 'ok' | 'error';
+        durationMs?: number;
+        outputPreview?: string;
+      },
+): Promise<ReportResult> {
+  let body: Record<string, unknown>;
+  if (event.type === 'model_reasoning') {
+    body = { step_type: 'thinking', content: { text: event.text } };
+  } else if (event.type === 'tool_call') {
+    await ctx.store?.set(toolNameKey(subject, event.callId), event.name).catch(() => {});
+    body = {
+      step_type: 'tool_call',
+      runtime_key: event.callId,
+      idempotency_key: `tc:${event.callId}`,
+      content: {
+        call_id: event.callId,
+        tool_name: event.name,
+        tool_input: event.input,
+        status: 'running',
+        started_at: new Date(ctx.now()).toISOString(),
+      },
+    };
+  } else {
+    const parked = await ctx.store?.get(toolNameKey(subject, event.callId)).catch(() => null);
+    await ctx.store?.delete(toolNameKey(subject, event.callId)).catch(() => {});
+    body = {
+      step_type: 'tool_result',
+      idempotency_key: `tr:${event.callId}`,
+      content: {
+        call_id: event.callId,
+        // The server REQUIRES tool_name on tool_result — a missed tool_call
+        // event (best-effort feed) must degrade to a labeled unknown, not a
+        // 400-dropped step.
+        tool_name: typeof parked === 'string' && parked ? parked : 'unknown',
+        status: event.status === 'error' ? 'error' : 'success',
+        output: event.outputPreview ?? '',
+        duration_ms: event.durationMs ?? 0,
+        collapsible: true,
+      },
+    };
+  }
+  try {
+    const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/agents/${parallAgentId(ctx)}/sessions/${sessionId}/steps`;
+    // The subject prefix tells chat turns from external IM turns — channel
+    // steps must not target 'chat' or the server would broadcast them onto
+    // a messages:{chv_} channel no client subscribes to (agent-core's
+    // resolveStepTarget draws the same line).
+    const targetType = subject.startsWith('chv_') ? 'channel_conversation' : 'chat';
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: jsonHeaders(ctx),
+      body: JSON.stringify({ ...body, target_type: targetType, target_id: subject }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (res.ok) return 'ok';
+    console.error(`[parel-channel] trace step failed (${res.status})`);
+    return resultForStatus(res.status);
+  } catch (err) {
+    console.error('[parel-channel] trace step failed', err);
+    return 'failed';
+  }
+}
+
+/**
+ * Lights the pending ring (server broadcasts dispatch.received). Must COMPLETE
+ * before the ack effect is returned: MarkReceived only transitions rows still
+ * in status='pending', and ack moves the same row to 'acked' — losing the race
+ * means the ring never appears.
+ */
+export async function markDispatchReceived(
+  ctx: ConnectorContext,
+  sourceType: string,
+  sourceId: string,
+): Promise<void> {
+  if (!reportingEnabled(ctx)) return;
+  try {
+    const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/dispatch/received`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: jsonHeaders(ctx),
+      body: JSON.stringify({ source_type: sourceType, source_id: sourceId }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!res.ok) console.error(`[parel-channel] mark received failed (${res.status})`);
+  } catch (err) {
+    console.error('[parel-channel] mark received failed', err);
+  }
+}