@parall/parel-channel 1.37.0

package/dist/session.d.ts

@@ -0,0 +1,110 @@
+import type { ConnectorContext } from '@parel/plugin-sdk';
+/**
+ * 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 declare const REQUEST_TIMEOUT_MS = 10000;
+/** Reporting needs the agent id in the endpoint path; old configs lack it. */
+export declare function reportingEnabled(ctx: ConnectorContext): boolean;
+/**
+ * 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 declare const turnEnvelopeKey: (subject: string) => string;
+/**
+ * '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';
+/** Drop the cached session id so the next ensureSession re-resolves it. */
+export declare function invalidateSession(ctx: ConnectorContext, subject: string): Promise<void>;
+/**
+ * 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 declare function ensureSession(ctx: ConnectorContext, subject: string, opts?: {
+    timeoutMs?: number;
+}): Promise<string | null>;
+/** PATCH the session (status / trigger_message_id). Never throws. */
+export declare function patchSession(ctx: ConnectorContext, sessionId: string, body: {
+    status: 'active' | 'idle';
+    trigger_message_id?: string;
+}): Promise<ReportResult>;
+/**
+ * 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 declare function createInputStep(ctx: ConnectorContext, sessionId: string, args: {
+    chatId: string;
+    messageId: string;
+    senderId?: string;
+    text: string;
+}): Promise<ReportResult>;
+/**
+ * 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 declare 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>;
+/**
+ * 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 declare 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>;
+/**
+ * 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 declare function markDispatchReceived(ctx: ConnectorContext, sourceType: string, sourceId: string): Promise<void>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAG1D;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,WAA8B,CAAC;AAG9E;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,GAAG,QAAQ,CAAC;AAMrD,2EAA2E;AAC3E,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7F;AASD;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyBxB;AAED,qEAAqE;AACrE,wBAAsB,YAAY,CAChC,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;IAAE,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/D,OAAO,CAAC,YAAY,CAAC,CAgBvB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3E,OAAO,CAAC,YAAY,CAAC,CA8BvB;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;IACJ,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,OAAO,CAAC,YAAY,CAAC,CAsCvB;AAOD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,EACD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACnE;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GACJ,OAAO,CAAC,YAAY,CAAC,CAyDvB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,gBAAgB,EACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/session.js

@@ -0,0 +1,284 @@
+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) {
+    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) => `turnEnvelope:${subject}`;
+const sessionKey = (subject) => `session:${subject}`;
+function resultForStatus(status) {
+    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, subject) {
+    await ctx.store?.delete(sessionKey(subject)).catch(() => { });
+}
+function jsonHeaders(ctx) {
+    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, subject, opts = {}) {
+    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));
+        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, sessionId, body) {
+    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, sessionId, args) {
+    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, sessionId, args) {
+    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, callId) => `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, sessionId, subject, event) {
+    let body;
+    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, sourceType, sourceId) {
+    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);
+    }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@parall/parel-channel",
+  "version": "1.37.0",
+  "description": "Parall channel plugin for the parel runtime — lets a parel agent treat Parall as a managed_ws channel (receive dispatches, reply via the Parall API)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/parall-hq/parall-mono",
+    "directory": "ts/parel-channel"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "parel.plugin.json"
+  ],
+  "dependencies": {
+    "@parel/plugin-sdk": "^0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run"
+  }
+}

package/parel.plugin.json

@@ -0,0 +1,26 @@
+{
+  "name": "@parall/parel-channel",
+  "type": "channel",
+  "channel": {
+    "connectionTypes": ["managed_ws"],
+    "sources": ["parall"]
+  },
+  "config": {
+    "parallApiUrl": "Parall API base URL (e.g. https://api.parall.com).",
+    "parallOrgId": "Parall org id this agent belongs to."
+  },
+  "requires": {
+    "secrets": {
+      "parallApiKey": {
+        "description": "This agent's Parall API key (agk_). Used to open the gateway WS and to post replies.",
+        "required": true
+      }
+    }
+  },
+  "execution": {
+    "snapshot": {
+      "store": "reset",
+      "sideEffects": "reference"
+    }
+  }
+}

package/src/channel-prompt.ts

@@ -0,0 +1,71 @@
+/**
+ * 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: string): string {
+  return value
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/[[\]|]/g, ' ')
+    .trim();
+}
+
+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 function buildChannelPrompt(args: ChannelPromptArgs): string {
+  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: ChannelPromptArgs): string {
+  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/src/connect.ts

@@ -0,0 +1,63 @@
+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 async function connectParall(ctx: ConnectorContext): Promise<ConnectRequest> {
+  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)) as { ticket?: string; ws_url?: string } | 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: ConnectorContext): string {
+  return String(ctx.config.parallApiUrl ?? '').replace(/\/+$/, '');
+}
+
+export function parallOrgId(ctx: ConnectorContext): string {
+  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: ConnectorContext): string {
+  return String(ctx.config.parallAgentId ?? '');
+}
+
+export function requireAgk(ctx: ConnectorContext): string {
+  const agk = ctx.secrets.parallApiKey;
+  if (!agk) {
+    throw new Error('parel-channel: parallApiKey secret is required');
+  }
+  return agk;
+}