@parall/parel-channel 1.37.0

package/dist/channel-prompt.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Prompt framing for external IM channel messages (channel_message
+ * dispatches). Mirrors agent-core's event-format.ts channel branch, adapted
+ * to the parel runtime's tool surface:
+ *
+ * - The audience is OUTSIDE Parall — no prll:// refs, no internal cards or
+ *   attachment links in the reply (dead links there).
+ * - The reply goes out through the provider clip's `send_message` command.
+ *   A parel agent invokes clips from its sandbox via the parall CLI, so the
+ *   hint spells out the concrete `parall clip invoke …` command (agent-core
+ *   leaves the invocation mechanism to the bridge's own clip tooling).
+ * - Provider metadata is best-effort (the connection lookup can fail) —
+ *   never instruct the agent to invoke a made-up clip alias.
+ * - When the inbound external message id is known, offer the in-thread reply
+ *   form ({"message_id": …}) so threaded conversations aren't nudged toward
+ *   new top-level messages.
+ */
+export interface ChannelPromptArgs {
+    /** Provider name (= clip alias, e.g. "feishu"); undefined when unresolved. */
+    provider?: string;
+    /** Conversation shape as recorded on the ChannelConversation (dm/group). */
+    conversationType?: string;
+    externalConversationId?: string;
+    externalMessageId?: string;
+    senderName: string;
+    /** The inbound message text (raw, un-framed). */
+    text: string;
+}
+export declare function buildChannelPrompt(args: ChannelPromptArgs): string;
+//# sourceMappingURL=channel-prompt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"channel-prompt.d.ts","sourceRoot":"","sources":["../src/channel-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAkBlE"}

package/dist/channel-prompt.js

@@ -0,0 +1,54 @@
+/**
+ * Prompt framing for external IM channel messages (channel_message
+ * dispatches). Mirrors agent-core's event-format.ts channel branch, adapted
+ * to the parel runtime's tool surface:
+ *
+ * - The audience is OUTSIDE Parall — no prll:// refs, no internal cards or
+ *   attachment links in the reply (dead links there).
+ * - The reply goes out through the provider clip's `send_message` command.
+ *   A parel agent invokes clips from its sandbox via the parall CLI, so the
+ *   hint spells out the concrete `parall clip invoke …` command (agent-core
+ *   leaves the invocation mechanism to the bridge's own clip tooling).
+ * - Provider metadata is best-effort (the connection lookup can fail) —
+ *   never instruct the agent to invoke a made-up clip alias.
+ * - When the inbound external message id is known, offer the in-thread reply
+ *   form ({"message_id": …}) so threaded conversations aren't nudged toward
+ *   new top-level messages.
+ */
+function sanitizeMeta(value) {
+    return value
+        .replace(/[\r\n]+/g, ' ')
+        .replace(/[[\]|]/g, ' ')
+        .trim();
+}
+export function buildChannelPrompt(args) {
+    const providerLabel = sanitizeMeta(args.provider ?? 'external IM');
+    const convLabel = args.externalConversationId
+        ? `${sanitizeMeta(args.externalConversationId)} (${sanitizeMeta(args.conversationType ?? 'conversation')})`
+        : sanitizeMeta(args.conversationType ?? 'conversation');
+    const lines = [
+        '[Event: channel.message]',
+        `[Channel: ${providerLabel} | conversation: ${convLabel}]`,
+        `[From: ${sanitizeMeta(args.senderName)} (external user, not a Parall member)]`,
+    ];
+    if (args.externalMessageId) {
+        lines.push(`[External message ID: ${sanitizeMeta(args.externalMessageId)}]`);
+    }
+    lines.push(`[Audience: this conversation lives on ${providerLabel}, OUTSIDE Parall. Readers cannot open prll:// links, Parall cards, or internal attachments — never include them in replies. Write plain conversational text.]`);
+    lines.push('', args.text);
+    return lines.join('\n') + buildChannelReplyHint(args);
+}
+function buildChannelReplyHint(args) {
+    const target = JSON.stringify({
+        chat_id: args.externalConversationId || '<conversation id>',
+        text: '...',
+    });
+    const threadAlt = args.externalMessageId
+        ? ` To reply in-thread to this specific message, use '${JSON.stringify({ message_id: args.externalMessageId, text: '...' })}' instead.`
+        : '';
+    if (args.provider) {
+        const alias = args.provider;
+        return `\n<system-reminder>To reply, invoke the \`${alias}\` clip's \`send_message\` command from your sandbox: \`parall clip invoke ${alias} send_message '${target}'\` — your plain text output is NOT delivered to the external conversation.${threadAlt} The same clip's \`call\` command reaches the wider ${alias} API when needed.</system-reminder>`;
+    }
+    return `\n<system-reminder>To reply, invoke your channel provider clip's \`send_message\` command from your sandbox: \`parall clip invoke <alias> send_message '${target}'\` (find the alias with \`parall clip list\`) — your plain text output is NOT delivered to the external conversation.${threadAlt} The same clip's \`call\` command reaches the wider external platform API when needed.</system-reminder>`;
+}

package/dist/connect.d.ts

@@ -0,0 +1,22 @@
+import type { ConnectorContext, ConnectRequest } from '@parel/plugin-sdk';
+/**
+ * Open the Parall gateway WebSocket as this agent. Auth is the agent's agk_: we
+ * fetch a short-lived WS ticket and hand parel the ws:// url to connect to. The
+ * parel runtime owns the socket lifecycle from there.
+ *
+ * Contract (confirmed against parel #102/#103): one long-lived managed_ws
+ * connection per declaration; the host rewrites ws(s):// to http(s):// for the
+ * Workers fetch dial, owns keepalive/liveness, and re-invokes connect() on
+ * every (re)connect — so the short-lived ticket is minted fresh each time.
+ */
+export declare function connectParall(ctx: ConnectorContext): Promise<ConnectRequest>;
+export declare function parallApiUrl(ctx: ConnectorContext): string;
+export declare function parallOrgId(ctx: ConnectorContext): string;
+/**
+ * The parall agent's user id (usr_), needed for the path-scoped session/step
+ * reporting endpoints. Empty on configs deployed before progress reporting
+ * shipped — reporting degrades to off until the agent is redeployed.
+ */
+export declare function parallAgentId(ctx: ConnectorContext): string;
+export declare function requireAgk(ctx: ConnectorContext): string;
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE1E;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAyBlF;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAE1D;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAE3D;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAMxD"}

package/dist/connect.js

@@ -0,0 +1,57 @@
+/**
+ * Open the Parall gateway WebSocket as this agent. Auth is the agent's agk_: we
+ * fetch a short-lived WS ticket and hand parel the ws:// url to connect to. The
+ * parel runtime owns the socket lifecycle from there.
+ *
+ * Contract (confirmed against parel #102/#103): one long-lived managed_ws
+ * connection per declaration; the host rewrites ws(s):// to http(s):// for the
+ * Workers fetch dial, owns keepalive/liveness, and re-invokes connect() on
+ * every (re)connect — so the short-lived ticket is minted fresh each time.
+ */
+export async function connectParall(ctx) {
+    const apiUrl = parallApiUrl(ctx);
+    const agk = requireAgk(ctx);
+    // connect() runs on every (re)connect — fail fast rather than hang the host's
+    // reconnect loop on a wedged ticket endpoint.
+    const res = await fetch(`${apiUrl}/api/v1/ws/ticket`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${agk}` },
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+        throw new Error(`parel-channel: ws ticket failed (${res.status})`);
+    }
+    const body = (await res.json().catch(() => null));
+    const ticket = body?.ticket;
+    const wsUrl = body?.ws_url;
+    if (!ticket) {
+        throw new Error('parel-channel: ws ticket response missing ticket');
+    }
+    // Prefer the server-advertised gateway URL — the API and WS hosts differ in
+    // some deployments (local dev ports, split domains). Fall back to deriving
+    // from the API origin (prod-style single domain routing /ws).
+    const base = wsUrl || `${apiUrl.replace(/^http/, 'ws')}/ws`;
+    const sep = base.includes('?') ? '&' : '?';
+    return { url: `${base}${sep}ticket=${encodeURIComponent(ticket)}` };
+}
+export function parallApiUrl(ctx) {
+    return String(ctx.config.parallApiUrl ?? '').replace(/\/+$/, '');
+}
+export function parallOrgId(ctx) {
+    return String(ctx.config.parallOrgId ?? '');
+}
+/**
+ * The parall agent's user id (usr_), needed for the path-scoped session/step
+ * reporting endpoints. Empty on configs deployed before progress reporting
+ * shipped — reporting degrades to off until the agent is redeployed.
+ */
+export function parallAgentId(ctx) {
+    return String(ctx.config.parallAgentId ?? '');
+}
+export function requireAgk(ctx) {
+    const agk = ctx.secrets.parallApiKey;
+    if (!agk) {
+        throw new Error('parel-channel: parallApiKey secret is required');
+    }
+    return agk;
+}

package/dist/delivery.d.ts

@@ -0,0 +1,24 @@
+import type { ChannelDelivery, ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
+/**
+ * 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 declare function buildParallDelivery(delivery: ChannelDelivery, ctx: ConnectorContext): Promise<ConnectorEffect[]>;
+//# sourceMappingURL=delivery.d.ts.map

package/dist/delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../src/delivery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAU5F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,eAAe,EACzB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CA2F5B"}

package/dist/delivery.js

@@ -0,0 +1,120 @@
+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, ctx) {
+    const apiUrl = parallApiUrl(ctx);
+    const agk = requireAgk(ctx);
+    const orgId = parallOrgId(ctx);
+    const route = (delivery.replyRoute?.data ?? {});
+    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;
+    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, subject, envelopeId, sessionId) {
+    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);
+    }
+}

package/dist/inbound.d.ts

@@ -0,0 +1,28 @@
+import type { AgentEvent, AgentEventEffect, ConnectorContext, ConnectorEffect, WebSocketFrame } from '@parel/plugin-sdk';
+export declare function handleParallFrame(frame: WebSocketFrame, 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
+ * truncated (bounded to keep a pathological backlog from wedging onOpen; the
+ * remainder is picked up on the next reconnect sweep).
+ */
+export declare function catchUpParall(ctx: ConnectorContext): Promise<ConnectorEffect[]>;
+/**
+ * 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 declare function handleParallAgentEvent(event: AgentEvent, ctx: ConnectorContext): Promise<AgentEventEffect[]>;
+//# sourceMappingURL=inbound.d.ts.map

package/dist/inbound.d.ts.map

@@ -0,0 +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;AA4C3B,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,CAiFrF;AA+XD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA2C7B"}