@parall/agent-core 1.36.1 → 1.38.0

package/dist/skills/parall-platform.js

@@ -98,16 +98,35 @@ original discussion and its approval/rejection IS the precedent.
 
 Each \`[Event: message.new]\` includes \`[Chat: ... (prll://cht_xxx)]\` — use that chat URI to reply.
 
+> **How you pass the message body matters — your command runs through a shell.**
+> Inside double quotes the shell expands \`$\`, backticks, and \`$(...)\` *before*
+> the CLI sees them: \`--text "That costs $1,000"\` sends \`That costs ,000\`, and
+> \`--text "$(cmd)"\` runs \`cmd\`. Single quotes instead break on apostrophes
+> (\`I'm\`, \`don't\`). So do **not** wrap real message content in quotes — pass it
+> through \`--text-file\` (a written file, or a quoted heredoc \`<<'EOF'\` that
+> disables all expansion). Reserve \`--text "..."\` for short literals with no
+> \`$\`, backtick, or apostrophe.
+
 \`\`\`bash
-# Reply to a chat (use the chat URI from the event)
-parall messages send prll://cht_xxx --text "Your reply"
+# One-off reply → quoted heredoc into stdin. The quoted delimiter <<'EOF'
+# disables ALL shell expansion, so $, backticks and apostrophes pass verbatim.
+parall messages send prll://cht_xxx --text-file - <<'PARALL_EOF'
+Sure — that's $1,000, and $(whoami) stays literal. I'm on it.
+PARALL_EOF
+
+# Longer / multi-line reply → write it with your file tool (no shell touches
+# the body), then point --text-file at the file.
+parall messages send prll://cht_xxx --text-file /tmp/reply.md
+
+# Short literal with no $, backtick, or apostrophe → --text is fine.
+parall messages send prll://cht_xxx --text "On it"
 
-# Direct message by user URI or display name
-parall dm prll://usr_xxx --text "Hello"
+# Direct message by user URI or display name (same --text-file / heredoc rules)
+parall dm prll://usr_xxx --text-file /tmp/reply.md
 parall dm "Alice" --text "Hello"
 
 # Thread reply
-parall messages send prll://cht_xxx --text "Reply" --thread-root-id 01JWC...
+parall messages send prll://cht_xxx --text-file /tmp/reply.md --thread-root-id 01JWC...
 
 # FYI message (no response expected — the recipient sees \`[Hint: no_reply]\`)
 parall messages send prll://cht_xxx --text "FYI: done" --no-reply
@@ -139,7 +158,9 @@ parall messages send prll://cht_xxx --attachment att_xxx --text "See attached"
 parall dm "Alice" --file /tmp/report.pdf --text "Report attached"
 \`\`\`
 
-\`--file\` and \`--attachment\` are mutually exclusive. \`--text\` can be combined with either.
+\`--file\` and \`--attachment\` are mutually exclusive. A caption (\`--text\` for
+short literals, or \`--text-file\` for anything with \`$\`, backticks, or quotes)
+can be combined with either.
 
 ## Approvals
 

package/dist/types.d.ts

@@ -26,7 +26,7 @@ export type DispatchState = {
 };
 /** Normalized inbound event from Parall. */
 export type ParallEvent = {
-    type: 'message' | 'task' | 'task_comment' | 'wiki_comment' | 'schedule' | 'external_trigger' | 'approval';
+    type: 'message' | 'task' | 'task_comment' | 'wiki_comment' | 'schedule' | 'external_trigger' | 'channel_message' | 'approval';
     targetId: string;
     targetName?: string;
     targetType?: string;
@@ -60,11 +60,20 @@ export type ParallEvent = {
     externalConnectionDisplayName?: string;
     externalIngressEventId?: string;
     externalIngressEventType?: string;
+    /** External IM channel metadata, used for channel_message events. */
+    channelProvider?: string;
+    channelConversationType?: string;
+    /** Provider-side conversation id (the send_message target). */
+    channelExternalConversationId?: string;
+    /** Provider-side message id (in-thread reply target). */
+    channelExternalMessageId?: string;
     /** Original event timestamp (e.g., message.created_at). When present,
      *  input steps use this instead of server insertion time for ordering. */
     sentAt?: string;
-    ackSourceType?: 'message' | 'task_activity' | 'comment' | 'schedule_run' | 'external_trigger_run';
+    ackSourceType?: 'message' | 'task_activity' | 'comment' | 'schedule_run' | 'external_trigger_run' | 'channel_message';
     ackSourceId?: string;
+    /** WorkItem id, when known (dispatch catch-up / re-drive hints carry it; live message.new does not). */
+    dispatchEventId?: string;
     /** Unread message count in the target chat since agent's last interaction. */
     unreadCount?: number;
     /** Channel cursor: the last message ID the agent read. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,mFAAmF;IACnF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EACA,SAAS,GACT,MAAM,GACN,cAAc,GACd,cAAc,GACd,UAAU,GACV,kBAAkB,GAClB,UAAU,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;8EAC0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,GAAG,sBAAsB,CAAC;IAClG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.36.1",
+  "version": "1.38.0",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "@opentelemetry/sdk-logs": "^0.57.0",
     "@opentelemetry/sdk-metrics": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
-    "@parall/sdk": "1.36.1"
+    "@parall/sdk": "1.38.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/bridge-workspace.ts

@@ -24,11 +24,21 @@ To say something in a chat, you **must** invoke the Parall CLI via your shell/ex
 
 All outbound interactions go through the \`parall\` CLI. Credentials are pre-injected as environment variables — no setup needed. If \`parall\` is not on PATH, use \`npx --yes @parall/cli@latest\` instead.
 
-- \`parall messages send prll://cht_xxx --text "..."\` — reply into the triggering chat
-- \`parall dm prll://usr_xxx --text "..." [--no-reply]\` — direct message another user
+- \`parall messages send prll://cht_xxx --text-file -\` — reply into the triggering chat (pipe the body via a quoted heredoc; see Shell-safety below)
+- \`parall dm prll://usr_xxx --text-file - [--no-reply]\` — direct message another user
 - \`parall tasks update prll://tsk_xxx --status in_progress\` — task state
 - \`parall no-reply [--reason "..."]\` — explicitly declare this turn silent (audit signal; not required for silence, just clarifies intent)
 
+**Shell-safety — never wrap real message content in double quotes.** Your command runs in a shell, which expands \`$\`, backticks, and \`$(...)\` inside \`"..."\` before the CLI sees them: \`--text "That costs $1,000"\` sends \`That costs ,000\`, and \`--text "$(cmd)"\` executes \`cmd\`. Pass message bodies via \`--text-file <path>\` (write the file first — no shell touches it) or a quoted heredoc that disables expansion:
+
+\`\`\`bash
+parall messages send prll://cht_xxx --text-file - <<'EOF'
+That costs $1,000, and $(whoami) stays literal. I'm on it.
+EOF
+\`\`\`
+
+Keep \`--text "..."\` for short literals with no \`$\`, backtick, or apostrophe.
+
 The bridge injects Parall context via environment variables. The static credentials \`PRLL_API_URL\`, \`PRLL_API_KEY\`, and \`PRLL_ORG_ID\` are always set. \`PRLL_CONTEXT_FILE\` points to a per-session JSON file that the gateway updates each dispatch with \`session_id\`, \`chat_id\`, \`trigger_message_id\`, \`no_reply\`, and \`step_id\` (updated per tool call). The CLI reads this file automatically — you do not need to pass \`--chat\` or \`--session\` explicitly when the context file is present.
 
 ## Attachments
@@ -73,7 +83,7 @@ Messages may arrive with a \`[Thread: prll://msg_xxx]\` line in the event block,
 
 ### CLI usage
 - The \`msg_xxx\` from the \`[Thread: prll://msg_xxx]\` line is the thread root ID — pass it as \`--thread-root-id\`
-- Reply in a thread: \`parall messages send <chatId> --text "..." --thread-root-id <msgId>\`
+- Reply in a thread: \`parall messages send <chatId> --text-file /tmp/reply.md --thread-root-id <msgId>\`
 - Read thread replies: \`parall messages list <chatId> --thread-root-id <msgId>\`
 
 ### Thread etiquette

package/src/dispatch-adapter.ts

@@ -23,6 +23,12 @@ export type DispatchContext = {
   contextFilePath?: string;
   /** @deprecated Use contextFilePath. Kept for runtimes that haven't migrated. */
   stepIdFilePath?: string;
+  /**
+   * PRLL_CONTEXT_DIR contract: the per-agent directory holding per-lane
+   * dispatch context files (`<lane-key>.json`, see lane-key.ts). Stable for
+   * the life of the bridge — safe to pin into spawn env.
+   */
+  contextDirPath?: string;
   client: ParallClient;
   log?: GatewayLogger;
 };

package/src/event-format.ts

@@ -89,6 +89,24 @@ export function buildEventBody(event: ParallEvent): string {
     if (event.scheduledFireAt) lines.push(`[Scheduled at: ${sanitizeMeta(event.scheduledFireAt)}]`);
     if (event.attachedUri) lines.push(`[Attached: ${sanitizeMeta(event.attachedUri)}]`);
     lines.push('', event.body);
+  } else if (event.type === 'channel_message') {
+    // External IM channel: the audience is OUTSIDE Parall. Frame the
+    // event so the agent writes for that audience — no prll:// refs, no
+    // internal cards/links in the reply body (they are dead links there).
+    lines.push(`[Event: channel.message]`);
+    const providerLabel = sanitizeMeta(event.channelProvider ?? 'external IM');
+    const convLabel = event.channelExternalConversationId
+      ? `${sanitizeMeta(event.channelExternalConversationId)} (${sanitizeMeta(event.channelConversationType ?? 'conversation')})`
+      : sanitizeMeta(event.channelConversationType ?? 'conversation');
+    lines.push(`[Channel: ${providerLabel} | conversation: ${convLabel}]`);
+    lines.push(`[From: ${sanitizeMeta(event.senderName)} (external user, not a Parall member)]`);
+    if (event.channelExternalMessageId) {
+      lines.push(`[External message ID: ${sanitizeMeta(event.channelExternalMessageId)}]`);
+    }
+    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('', event.body);
   } else if (event.type === 'external_trigger') {
     lines.push(`[Event: external.trigger]`);
     lines.push(`[Trigger: prll://${event.targetId}]`);
@@ -134,7 +152,7 @@ function buildSendMessageHint(event: ParallEvent): string {
   }
 
   if (event.targetId.startsWith('cht_')) {
-    return `\n<system-reminder>To reply, run: \`parall messages send prll://${event.targetId} --text "..."\` — your plain text output is not delivered to the chat.</system-reminder>`;
+    return `\n<system-reminder>To reply, run \`parall messages send prll://${event.targetId} --text-file - <<'EOF'\` … \`EOF\` — the quoted heredoc keeps \`$\`, backticks and apostrophes literal (plain \`--text "$1,000"\` sends \`,000\`). Your plain text output is not delivered to the chat.</system-reminder>`;
   }
 
   if (event.targetId.startsWith('tsk_')) {
@@ -145,6 +163,25 @@ function buildSendMessageHint(event: ParallEvent): string {
     return `\n<system-reminder>To communicate, use the CLI: \`parall messages send\` / \`parall dm\`. Your plain text output is not delivered.</system-reminder>`;
   }
 
+  if (event.type === 'channel_message') {
+    // Provider metadata is best-effort (the gateway's connection lookup can
+    // fail) — never instruct the agent to invoke a made-up clip alias.
+    const clipLabel = event.channelProvider
+      ? `the \`${event.channelProvider}\` clip's`
+      : "your channel provider clip's";
+    const apiLabel = event.channelProvider ?? 'external platform';
+    const target = event.channelExternalConversationId
+      ? `{"chat_id": "${event.channelExternalConversationId}", "text": "..."}`
+      : `{"chat_id": "<conversation id>", "text": "..."}`;
+    // Offer the in-thread alternative whenever the inbound message id is
+    // known — otherwise the hint nudges every threaded conversation toward a
+    // new top-level message.
+    const threadAlt = event.channelExternalMessageId
+      ? ` To reply in-thread to this specific message, use {"message_id": "${event.channelExternalMessageId}", "text": "..."} instead.`
+      : '';
+    return `\n<system-reminder>To reply, invoke ${clipLabel} \`send_message\` command with ${target} — your plain text output is NOT delivered to the external conversation.${threadAlt} The same clip's \`call\` command reaches the wider ${apiLabel} API when needed.</system-reminder>`;
+  }
+
   if (event.type === 'external_trigger' || event.targetId.startsWith('xtr_')) {
     return `\n<system-reminder>This external trigger is incoming-only. Your plain text output is not sent back to the external provider. To communicate in Parall, use \`parall messages send\` / \`parall dm\`; provider-specific outbound actions require a separate capability.</system-reminder>`;
   }