@parall/parel-channel 1.40.0 → 1.41.0

package/dist/inbound-channel.d.ts

@@ -0,0 +1,29 @@
+import type { ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
+/**
+ * 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 declare const PROVIDER_LOOKUP_TIMEOUT_MS = 3000;
+/**
+ * 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 declare function effectsForChannelDispatch(sourceId: string, dispatchId: string, ctx: ConnectorContext): Promise<ConnectorEffect[]>;
+//# sourceMappingURL=inbound-channel.d.ts.map

package/dist/inbound-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-channel.d.ts","sourceRoot":"","sources":["../src/inbound-channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAc3E;;;;GAIG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAuJ5B"}

package/dist/inbound-channel.js

@@ -0,0 +1,213 @@
+import { buildChannelPrompt } from './channel-prompt.js';
+import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
+import { ackEffect, createChannelInputStep, ensureSession, invalidateSession, markDispatchReceived, patchSession, REQUEST_TIMEOUT_MS, TURN_ENVELOPE_KEY, } 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, dispatchId, ctx) {
+    const apiUrl = parallApiUrl(ctx);
+    const orgId = parallOrgId(ctx);
+    const authHeaders = { Authorization: `Bearer ${requireAgk(ctx)}` };
+    const get = (path, timeoutMs = 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));
+    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));
+    // 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);
+    if (sessionId) {
+        await ctx.store?.set(TURN_ENVELOPE_KEY, envelopeId).catch(() => { });
+        const report = (sid) => 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;
+    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.
+            },
+        },
+        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; any failure returns undefined — prompt wording degrades to
+ * neutral rather than inventing a clip alias.
+ */
+async function resolveChannelProvider(ctx, connectionId, get) {
+    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));
+        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, conversationId, sessionId) {
+    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);
+    }
+}

package/dist/inbound.d.ts

@@ -1,5 +1,19 @@
 import type { AgentEvent, AgentEventEffect, ConnectorContext, ConnectorEffect, WebSocketFrame } from '@parel/plugin-sdk';
+/** Surface a violated isolation assumption as a log line, not silent
+ * mis-serialization (see the chain doc above). */
+export declare function assertChainConnection(ctx: ConnectorContext): void;
+export declare function serialized<T>(fn: () => Promise<T>): Promise<T>;
 export declare function handleParallFrame(frame: WebSocketFrame, ctx: ConnectorContext): Promise<ConnectorEffect[]>;
+/**
+ * Fork retry timers (armed by child_spawn_failed): re-plan the stranded
+ * message through the normal dispatch pipeline. onTimer returns the FULL
+ * effect union (unlike onAgentEvent), so the re-plan can emit/spawn/ack.
+ * The parked row is cleared first — a re-plan that fails transiently leaves
+ * the WorkItem in `received` for the reconnect sweep, same as any dispatch.
+ */
+export declare function handleParallTimer(timer: {
+    key: string;
+}, ctx: ConnectorContext): Promise<ConnectorEffect[]>;
 /**
  * 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

package/dist/inbound.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../src/inbound.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACf,MAAM,mBAAmB,CAAC;AAiD3B,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAiB5B;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAuDrF;AAkdD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAyD7B"}
+{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../src/inbound.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACf,MAAM,mBAAmB,CAAC;AAwG3B;kDACkD;AAClD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CASjE;AACD,wBAAgB,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAO9D;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAG5B;AAwCD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EACtB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAE5B;AA8BD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAE/E;AAgmBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAE7B"}