@parall/agent-core 1.17.0 → 1.18.1

package/dist/bridge-workspace.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared workspace instructions seeded into every self-hosted bridge runtime
+ * (Claude Code writes this to `CLAUDE.md`, Codex to `AGENTS.md`). The text and
+ * the Parall CLI detection helpers live together so the seeded command
+ * examples and the runtime-side suppression logic cannot drift apart. Each
+ * bridge package is responsible for its own filesystem write —
+ * `@parall/agent-core` stays runtime-neutral and exports only text + pure
+ * helpers here.
+ */
+export declare const BRIDGE_WORKSPACE_INSTRUCTIONS = "# Agent workspace\n\nYou are an agent in Parall IM. You participate in chats, handle tasks, and interact exclusively through the Parall CLI.\n\n## Message Model\n\nIncoming events are rendered as structured `[Event: ...]` blocks.\nEach event includes `[Chat: ... (prll://cht_xxx)]` \u2014 use that chat ID (or full URI) when replying.\n\n**Your plain-text output is not delivered to anyone** \u2014 it is recorded as suppressed thinking in your session steps and discarded from the chat.\nTo say something in a chat, you **must** invoke the Parall CLI via your shell/exec tool. To stay silent, simply do not invoke it.\n\n## Parall CLI\n\nAll outbound interactions go through `@parall/cli`. Credentials are pre-injected as environment variables \u2014 no setup needed.\n\n- `npx --yes @parall/cli@latest messages send prll://cht_xxx --text \"...\"` \u2014 reply into the triggering chat\n- `npx --yes @parall/cli@latest dm prll://usr_xxx --text \"...\" [--no-reply]` \u2014 direct message another user\n- `npx --yes @parall/cli@latest tasks update prll://tsk_xxx --status in_progress` \u2014 task state\n- `npx --yes @parall/cli@latest no-reply [--reason \"...\"]` \u2014 explicitly declare this turn silent (audit signal; not required for silence, just clarifies intent)\n\nThe bridge injects Parall context via environment variables. The static credentials `PRLL_API_URL`, `PRLL_API_KEY`, and `PRLL_ORG_ID` are always set. Per-dispatch context \u2014 `PRLL_SESSION_ID`, `PRLL_CHAT_ID`, `PRLL_TRIGGER_MESSAGE_ID`, `PRLL_STEP_ID_FILE` \u2014 is set in subprocess-per-dispatch runtimes (Claude Code); in long-running runtimes (Codex) those may be absent and the CLI will fall back to whatever defaults you supply on the command line.\n\n## Guardrails\n\n- A dispatch may coalesce multiple events. Decide per event whether to reply via `messages send` / `dm` \u2014 events you do not act on simply receive no reply.\n- If an event carries `[Hint: no_reply]`, do not send anything for that event. `no-reply` is optional and only useful as an explicit intent marker.\n- Never try to \"speak\" by typing sentences like \"No response needed\" / \"Noted\" / \"OK\" \u2014 they are discarded, so they accomplish nothing except polluting your session log.\n- Keep CLI replies concise and task-focused.\n\nSee `docs/engineering-design/agent-dm-loop-prevention.md` \u00A7 Layer 0 for why plain text is never auto-projected.\n";
+/** Extracts the `command` string from a shell/bash tool call's input payload. */
+export declare function extractShellCommand(input: unknown): string | undefined;
+/**
+ * Returns the non-flag tokens that follow a Parall CLI invocation in
+ * `command`, or `null` if the command isn't a Parall CLI call.
+ *
+ * Handles all documented launch forms — bare `parall`, `npx [--yes|-y]
+ * @parall/cli[@version]`, `pnpm (exec|dlx) parall` — and skips npx flags so
+ * `npx --yes` matches the same way as `npx -y`. Uses space-delimited
+ * tokenization rather than a regex so that `messages send --no-reply` is
+ * correctly classified as a `messages send` invocation (not the receiver-side
+ * `no-reply` subcommand).
+ */
+export declare function parseParallCliInvocation(command: string): string[] | null;
+/**
+ * Detects whether a shell command invokes the Parall CLI to send a
+ * chat-visible side effect (`messages send` or `dm`). Bridge adapters use
+ * this to suppress the immediately-following runtime text so the user
+ * doesn't see the same message twice — once from the CLI call, once
+ * projected from runtime output.
+ */
+export declare function isParallSendCommand(command: string | undefined): boolean;
+/**
+ * Detects whether a shell command invokes `parall no-reply`, which signals
+ * the agent wants the whole turn silenced. Bridge adapters use this to
+ * flip a sticky suppression flag for the rest of the dispatch so no text
+ * event from that turn is projected into chat.
+ */
+export declare function isParallNoReplyCommand(command: string | undefined): boolean;
+//# sourceMappingURL=bridge-workspace.d.ts.map

package/dist/bridge-workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-workspace.d.ts","sourceRoot":"","sources":["../src/bridge-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,6BAA6B,m3EA+BzC,CAAC;AAEF,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAItE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAmBzE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAKxE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAI3E"}

package/dist/bridge-workspace.js

@@ -0,0 +1,113 @@
+/**
+ * Shared workspace instructions seeded into every self-hosted bridge runtime
+ * (Claude Code writes this to `CLAUDE.md`, Codex to `AGENTS.md`). The text and
+ * the Parall CLI detection helpers live together so the seeded command
+ * examples and the runtime-side suppression logic cannot drift apart. Each
+ * bridge package is responsible for its own filesystem write —
+ * `@parall/agent-core` stays runtime-neutral and exports only text + pure
+ * helpers here.
+ */
+export const BRIDGE_WORKSPACE_INSTRUCTIONS = `# Agent workspace
+
+You are an agent in Parall IM. You participate in chats, handle tasks, and interact exclusively through the Parall CLI.
+
+## Message Model
+
+Incoming events are rendered as structured \`[Event: ...]\` blocks.
+Each event includes \`[Chat: ... (prll://cht_xxx)]\` — use that chat ID (or full URI) when replying.
+
+**Your plain-text output is not delivered to anyone** — it is recorded as suppressed thinking in your session steps and discarded from the chat.
+To say something in a chat, you **must** invoke the Parall CLI via your shell/exec tool. To stay silent, simply do not invoke it.
+
+## Parall CLI
+
+All outbound interactions go through \`@parall/cli\`. Credentials are pre-injected as environment variables — no setup needed.
+
+- \`npx --yes @parall/cli@latest messages send prll://cht_xxx --text "..."\` — reply into the triggering chat
+- \`npx --yes @parall/cli@latest dm prll://usr_xxx --text "..." [--no-reply]\` — direct message another user
+- \`npx --yes @parall/cli@latest tasks update prll://tsk_xxx --status in_progress\` — task state
+- \`npx --yes @parall/cli@latest no-reply [--reason "..."]\` — explicitly declare this turn silent (audit signal; not required for silence, just clarifies intent)
+
+The bridge injects Parall context via environment variables. The static credentials \`PRLL_API_URL\`, \`PRLL_API_KEY\`, and \`PRLL_ORG_ID\` are always set. Per-dispatch context — \`PRLL_SESSION_ID\`, \`PRLL_CHAT_ID\`, \`PRLL_TRIGGER_MESSAGE_ID\`, \`PRLL_STEP_ID_FILE\` — is set in subprocess-per-dispatch runtimes (Claude Code); in long-running runtimes (Codex) those may be absent and the CLI will fall back to whatever defaults you supply on the command line.
+
+## Guardrails
+
+- A dispatch may coalesce multiple events. Decide per event whether to reply via \`messages send\` / \`dm\` — events you do not act on simply receive no reply.
+- If an event carries \`[Hint: no_reply]\`, do not send anything for that event. \`no-reply\` is optional and only useful as an explicit intent marker.
+- Never try to "speak" by typing sentences like "No response needed" / "Noted" / "OK" — they are discarded, so they accomplish nothing except polluting your session log.
+- Keep CLI replies concise and task-focused.
+
+See \`docs/engineering-design/agent-dm-loop-prevention.md\` § Layer 0 for why plain text is never auto-projected.
+`;
+/** Extracts the `command` string from a shell/bash tool call's input payload. */
+export function extractShellCommand(input) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    const command = input.command;
+    return typeof command === "string" && command.trim() ? command.trim() : undefined;
+}
+/**
+ * Returns the non-flag tokens that follow a Parall CLI invocation in
+ * `command`, or `null` if the command isn't a Parall CLI call.
+ *
+ * Handles all documented launch forms — bare `parall`, `npx [--yes|-y]
+ * @parall/cli[@version]`, `pnpm (exec|dlx) parall` — and skips npx flags so
+ * `npx --yes` matches the same way as `npx -y`. Uses space-delimited
+ * tokenization rather than a regex so that `messages send --no-reply` is
+ * correctly classified as a `messages send` invocation (not the receiver-side
+ * `no-reply` subcommand).
+ */
+export function parseParallCliInvocation(command) {
+    const tokens = command.replace(/\s+/g, " ").trim().split(" ");
+    let i = 0;
+    if (tokens[i] === "parall") {
+        i++;
+    }
+    else if (tokens[i] === "npx") {
+        i++;
+        while (i < tokens.length && tokens[i].startsWith("-"))
+            i++;
+        if (i >= tokens.length || !/^@parall\/cli(?:@.+)?$/.test(tokens[i]))
+            return null;
+        i++;
+    }
+    else if (tokens[i] === "pnpm") {
+        i++;
+        if (i < tokens.length && (tokens[i] === "exec" || tokens[i] === "dlx"))
+            i++;
+        if (i >= tokens.length || tokens[i] !== "parall")
+            return null;
+        i++;
+    }
+    else {
+        return null;
+    }
+    return tokens.slice(i).filter((t) => !t.startsWith("-"));
+}
+/**
+ * Detects whether a shell command invokes the Parall CLI to send a
+ * chat-visible side effect (`messages send` or `dm`). Bridge adapters use
+ * this to suppress the immediately-following runtime text so the user
+ * doesn't see the same message twice — once from the CLI call, once
+ * projected from runtime output.
+ */
+export function isParallSendCommand(command) {
+    if (!command)
+        return false;
+    const sub = parseParallCliInvocation(command);
+    if (!sub || sub.length === 0)
+        return false;
+    return sub[0] === "dm" || (sub[0] === "messages" && sub[1] === "send");
+}
+/**
+ * Detects whether a shell command invokes `parall no-reply`, which signals
+ * the agent wants the whole turn silenced. Bridge adapters use this to
+ * flip a sticky suppression flag for the rest of the dispatch so no text
+ * event from that turn is projected into chat.
+ */
+export function isParallNoReplyCommand(command) {
+    if (!command)
+        return false;
+    const sub = parseParallCliInvocation(command);
+    return sub?.[0] === "no-reply";
+}

package/dist/event-format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-format.d.ts","sourceRoot":"","sources":["../src/event-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA+BzD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CASnE"}
+{"version":3,"file":"event-format.d.ts","sourceRoot":"","sources":["../src/event-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAwCzD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CASnE"}

package/dist/event-format.js

@@ -25,6 +25,16 @@ export function buildEventBody(event) {
         }
         lines.push("", event.body);
     }
+    else if (event.type === "task_comment") {
+        lines.push(`[Event: task.comment.created]`);
+        const taskLabel = event.targetName
+            ? `${event.targetName} (prll://${event.targetId})`
+            : `prll://${event.targetId}`;
+        lines.push(`[Task: ${taskLabel}]`);
+        lines.push(`[From: ${event.senderName} (prll://${event.senderId})]`);
+        lines.push(`[Comment ID: prll://${event.messageId}]`);
+        lines.push("", event.body);
+    }
     else {
         lines.push(`[Event: task.assigned]`);
         const taskLabel = event.targetName

package/dist/gateway-base.d.ts

@@ -62,6 +62,7 @@ export declare class ParallAgentGateway {
     private buildMessageDispatchDecision;
     private handleMessage;
     private handleTaskAssignment;
+    private handleTaskComment;
     private catchUpFromDispatch;
     private handleHello;
     private shutdown;

package/dist/gateway-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-base.d.ts","sourceRoot":"","sources":["../src/gateway-base.ts"],"names":[],"mappings":"AAIA,OAAO,EAAuB,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EACV,qBAAqB,EAQtB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAEV,eAAe,EAGf,aAAa,EAEd,MAAM,uBAAuB,CAAC;AAoD/B,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,EAAE,EAAE,QAAQ,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,eAAe,EAAE,eAAe,CAAC;IACjC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACtE,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,QAAQ,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjH,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACjD,CAAC;AAkCF,qBAAa,kBAAkB;IAuBjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAtBjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IACjE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAK5B;IAEF,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAQ;IAChD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;gBAEjB,IAAI,EAAE,oBAAoB;IAIjD,GAAG,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA8ElD,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,oBAAoB;YAmBd,eAAe;YAqBf,iBAAiB;IAsF/B,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;YAQT,gCAAgC;YAMhC,WAAW;YAyDX,gBAAgB;YAmEhB,eAAe;YAmDf,kBAAkB;YAoElB,kBAAkB;YAkBlB,4BAA4B;YAoD5B,aAAa;YA8Bb,oBAAoB;YAmCpB,mBAAmB;YAoGnB,WAAW;YA0DX,QAAQ;CAsBvB"}
+{"version":3,"file":"gateway-base.d.ts","sourceRoot":"","sources":["../src/gateway-base.ts"],"names":[],"mappings":"AAIA,OAAO,EAAuB,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EACV,qBAAqB,EAUtB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAEV,eAAe,EAGf,aAAa,EAEd,MAAM,uBAAuB,CAAC;AAoD/B,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,EAAE,EAAE,QAAQ,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,eAAe,EAAE,eAAe,CAAC;IACjC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACtE,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,QAAQ,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjH,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACjD,CAAC;AAkCF,qBAAa,kBAAkB;IAuBjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAtBjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IACjE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAK5B;IAEF,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAQ;IAChD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;gBAEjB,IAAI,EAAE,oBAAoB;IAIjD,GAAG,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA2FlD,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,oBAAoB;YAmBd,eAAe;YAqBf,iBAAiB;IAsF/B,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;YAQT,gCAAgC;YAMhC,WAAW;YAyDX,gBAAgB;YAmEhB,eAAe;YAmDf,kBAAkB;YAoElB,kBAAkB;YAkBlB,4BAA4B;YAoD5B,aAAa;YA8Bb,oBAAoB;YAmCpB,iBAAiB;YAqEjB,mBAAmB;YAsGnB,WAAW;YA0DX,QAAQ;CAsBvB"}

package/dist/gateway-base.js

@@ -121,6 +121,21 @@ export class ParallAgentGateway {
                 this.opts.log?.error(`parall[${this.opts.accountId}]: task dispatch failed for ${data.id}: ${String(err)}`);
             }
         });
+        ws.on("dispatch.new", async (data) => {
+            if (data.event_type !== "task_comment")
+                return;
+            if (!data.source_id || !data.task_id)
+                return;
+            try {
+                const dispatched = await this.handleTaskComment(data.source_id, data.task_id, data.actor_id);
+                if (dispatched) {
+                    this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => { });
+                }
+            }
+            catch (err) {
+                this.opts.log?.error(`parall[${this.opts.accountId}]: task comment dispatch failed for ${data.source_id}: ${String(err)}`);
+            }
+        });
         this.opts.log?.info(`parall[${this.opts.accountId}]: connecting to ${this.opts.connectionLabel ?? "Parall WS"}...`);
         await ws.connect();
         return new Promise((resolve) => {
@@ -198,8 +213,8 @@ export class ParallAgentGateway {
                 target_type: target.target_type,
                 target_id: target.target_id,
                 content: {
-                    trigger_type: event.type === "task" ? "task_assign" : "mention",
-                    trigger_ref: event.type === "task" ? { task_id: event.targetId } : { message_id: event.messageId },
+                    trigger_type: event.type === "task" ? "task_assign" : event.type === "task_comment" ? "task_comment" : "mention",
+                    trigger_ref: event.type === "task" ? { task_id: event.targetId } : event.type === "task_comment" ? { comment_id: event.messageId, task_id: event.targetId } : { message_id: event.messageId },
                     sender_id: event.senderId,
                     sender_name: event.senderName,
                     summary: event.body.substring(0, 200),
@@ -673,6 +688,73 @@ export class ParallAgentGateway {
         }
         return dispatched;
     }
+    async handleTaskComment(commentId, taskId, actorId) {
+        const dedupeKey = `comment:${commentId}`;
+        if (this.dispatchedTasks.has(dedupeKey))
+            return false;
+        this.dispatchedTasks.add(dedupeKey);
+        let comment = null;
+        try {
+            comment = await this.opts.client.getComment(this.opts.config.org_id, commentId);
+        }
+        catch (err) {
+            const status = err?.status;
+            if (status === 404) {
+                // Comment deleted — ack stale dispatch so it doesn't pile up.
+                this.opts.log?.info(`parall[${this.opts.accountId}]: skipping deleted comment ${commentId}, acking stale dispatch`);
+                this.dispatchedTasks.delete(dedupeKey);
+                return true; // caller will ack
+            }
+            this.dispatchedTasks.delete(dedupeKey);
+            return false; // transient error — leave pending for retry
+        }
+        if (!comment) {
+            this.dispatchedTasks.delete(dedupeKey);
+            return true; // null response = gone, ack stale dispatch
+        }
+        let task = null;
+        try {
+            task = await this.opts.client.getTask(this.opts.config.org_id, taskId);
+        }
+        catch { /* task context is optional */ }
+        const taskLabel = task ? `${task.identifier ?? task.id} "${task.title}"` : taskId;
+        this.opts.log?.info(`parall[${this.opts.accountId}]: task comment on ${taskLabel} by ${actorId ?? "unknown"}`);
+        const parts = [];
+        if (task) {
+            parts.push(`Task: ${task.title} (prll://${task.id})`);
+            parts.push(`Status: ${task.status}`, `Priority: ${task.priority}`);
+        }
+        else {
+            parts.push(`Task: prll://${taskId}`);
+        }
+        parts.push(`Comment by: ${comment.author?.display_name ?? actorId ?? "unknown"} (prll://${comment.author_id})`);
+        parts.push("", comment.body);
+        const event = {
+            type: "task_comment",
+            targetId: taskId,
+            targetName: task?.identifier ?? undefined,
+            targetType: "task",
+            senderId: comment.author_id,
+            senderName: comment.author?.display_name ?? actorId ?? "unknown",
+            messageId: commentId,
+            body: parts.join("\n"),
+            ackSourceType: "comment",
+            ackSourceId: commentId,
+        };
+        let dispatched;
+        try {
+            dispatched = await this.handleInboundEvent(event);
+        }
+        catch (err) {
+            // Clear dedupe key so the event remains retryable on next catch-up.
+            this.dispatchedTasks.delete(dedupeKey);
+            throw err;
+        }
+        if (!dispatched) {
+            this.dispatchedTasks.delete(dedupeKey);
+        }
+        return dispatched;
+    }
     async catchUpFromDispatch(coldStart = false) {
         const minAge = coldStart ? Date.now() - this.COLD_START_WINDOW_MS : 0;
         let cursor;
@@ -722,6 +804,9 @@ export class ParallAgentGateway {
                             dispatched = true;
                         }
                     }
+                    else if (item.event_type === "task_comment" && item.source_id && item.task_id) {
+                        dispatched = await this.handleTaskComment(item.source_id, item.task_id, item.actor_id);
+                    }
                     else if (item.event_type === "message" && item.source_id && item.chat_id) {
                         if (!this.tryClaimMessage(item.source_id))
                             continue;

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from "./session-state.js";
 export * from "./routing.js";
 export * from "./event-format.js";
 export * from "./prompt-fragments.js";
+export * from "./bridge-workspace.js";
 export * from "./dispatch-adapter.js";
 export * from "./gateway-base.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -3,5 +3,6 @@ export * from "./session-state.js";
 export * from "./routing.js";
 export * from "./event-format.js";
 export * from "./prompt-fragments.js";
+export * from "./bridge-workspace.js";
 export * from "./dispatch-adapter.js";
 export * from "./gateway-base.js";

package/dist/types.d.ts

@@ -18,7 +18,7 @@ export type DispatchState = {
 };
 /** Normalized inbound event from Parall. */
 export type ParallEvent = {
-    type: "message" | "task";
+    type: "message" | "task" | "task_comment";
     targetId: string;
     targetName?: string;
     targetType?: string;
@@ -34,7 +34,7 @@ export type ParallEvent = {
         fileSize: number;
         mimeType: string;
     }>;
-    ackSourceType?: "message" | "task_activity";
+    ackSourceType?: "message" | "task_activity" | "comment";
     ackSourceId?: string;
 };
 //# sourceMappingURL=types.d.ts.map

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,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,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;CAC3B,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,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,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}
+{"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,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,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;CAC3B,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,cAAc,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,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,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,CAAC;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.17.0",
+  "version": "1.18.1",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -22,7 +22,7 @@
     "src"
   ],
   "dependencies": {
-    "@parall/sdk": "1.17.0"
+    "@parall/sdk": "1.18.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/bridge-workspace.ts

@@ -0,0 +1,107 @@
+/**
+ * Shared workspace instructions seeded into every self-hosted bridge runtime
+ * (Claude Code writes this to `CLAUDE.md`, Codex to `AGENTS.md`). The text and
+ * the Parall CLI detection helpers live together so the seeded command
+ * examples and the runtime-side suppression logic cannot drift apart. Each
+ * bridge package is responsible for its own filesystem write —
+ * `@parall/agent-core` stays runtime-neutral and exports only text + pure
+ * helpers here.
+ */
+
+export const BRIDGE_WORKSPACE_INSTRUCTIONS = `# Agent workspace
+
+You are an agent in Parall IM. You participate in chats, handle tasks, and interact exclusively through the Parall CLI.
+
+## Message Model
+
+Incoming events are rendered as structured \`[Event: ...]\` blocks.
+Each event includes \`[Chat: ... (prll://cht_xxx)]\` — use that chat ID (or full URI) when replying.
+
+**Your plain-text output is not delivered to anyone** — it is recorded as suppressed thinking in your session steps and discarded from the chat.
+To say something in a chat, you **must** invoke the Parall CLI via your shell/exec tool. To stay silent, simply do not invoke it.
+
+## Parall CLI
+
+All outbound interactions go through \`@parall/cli\`. Credentials are pre-injected as environment variables — no setup needed.
+
+- \`npx --yes @parall/cli@latest messages send prll://cht_xxx --text "..."\` — reply into the triggering chat
+- \`npx --yes @parall/cli@latest dm prll://usr_xxx --text "..." [--no-reply]\` — direct message another user
+- \`npx --yes @parall/cli@latest tasks update prll://tsk_xxx --status in_progress\` — task state
+- \`npx --yes @parall/cli@latest no-reply [--reason "..."]\` — explicitly declare this turn silent (audit signal; not required for silence, just clarifies intent)
+
+The bridge injects Parall context via environment variables. The static credentials \`PRLL_API_URL\`, \`PRLL_API_KEY\`, and \`PRLL_ORG_ID\` are always set. Per-dispatch context — \`PRLL_SESSION_ID\`, \`PRLL_CHAT_ID\`, \`PRLL_TRIGGER_MESSAGE_ID\`, \`PRLL_STEP_ID_FILE\` — is set in subprocess-per-dispatch runtimes (Claude Code); in long-running runtimes (Codex) those may be absent and the CLI will fall back to whatever defaults you supply on the command line.
+
+## Guardrails
+
+- A dispatch may coalesce multiple events. Decide per event whether to reply via \`messages send\` / \`dm\` — events you do not act on simply receive no reply.
+- If an event carries \`[Hint: no_reply]\`, do not send anything for that event. \`no-reply\` is optional and only useful as an explicit intent marker.
+- Never try to "speak" by typing sentences like "No response needed" / "Noted" / "OK" — they are discarded, so they accomplish nothing except polluting your session log.
+- Keep CLI replies concise and task-focused.
+
+See \`docs/engineering-design/agent-dm-loop-prevention.md\` § Layer 0 for why plain text is never auto-projected.
+`;
+
+/** Extracts the `command` string from a shell/bash tool call's input payload. */
+export function extractShellCommand(input: unknown): string | undefined {
+  if (!input || typeof input !== "object") return undefined;
+  const command = (input as { command?: unknown }).command;
+  return typeof command === "string" && command.trim() ? command.trim() : undefined;
+}
+
+/**
+ * Returns the non-flag tokens that follow a Parall CLI invocation in
+ * `command`, or `null` if the command isn't a Parall CLI call.
+ *
+ * Handles all documented launch forms — bare `parall`, `npx [--yes|-y]
+ * @parall/cli[@version]`, `pnpm (exec|dlx) parall` — and skips npx flags so
+ * `npx --yes` matches the same way as `npx -y`. Uses space-delimited
+ * tokenization rather than a regex so that `messages send --no-reply` is
+ * correctly classified as a `messages send` invocation (not the receiver-side
+ * `no-reply` subcommand).
+ */
+export function parseParallCliInvocation(command: string): string[] | null {
+  const tokens = command.replace(/\s+/g, " ").trim().split(" ");
+  let i = 0;
+  if (tokens[i] === "parall") {
+    i++;
+  } else if (tokens[i] === "npx") {
+    i++;
+    while (i < tokens.length && tokens[i].startsWith("-")) i++;
+    if (i >= tokens.length || !/^@parall\/cli(?:@.+)?$/.test(tokens[i])) return null;
+    i++;
+  } else if (tokens[i] === "pnpm") {
+    i++;
+    if (i < tokens.length && (tokens[i] === "exec" || tokens[i] === "dlx")) i++;
+    if (i >= tokens.length || tokens[i] !== "parall") return null;
+    i++;
+  } else {
+    return null;
+  }
+  return tokens.slice(i).filter((t) => !t.startsWith("-"));
+}
+
+/**
+ * Detects whether a shell command invokes the Parall CLI to send a
+ * chat-visible side effect (`messages send` or `dm`). Bridge adapters use
+ * this to suppress the immediately-following runtime text so the user
+ * doesn't see the same message twice — once from the CLI call, once
+ * projected from runtime output.
+ */
+export function isParallSendCommand(command: string | undefined): boolean {
+  if (!command) return false;
+  const sub = parseParallCliInvocation(command);
+  if (!sub || sub.length === 0) return false;
+  return sub[0] === "dm" || (sub[0] === "messages" && sub[1] === "send");
+}
+
+/**
+ * Detects whether a shell command invokes `parall no-reply`, which signals
+ * the agent wants the whole turn silenced. Bridge adapters use this to
+ * flip a sticky suppression flag for the rest of the dispatch so no text
+ * event from that turn is projected into chat.
+ */
+export function isParallNoReplyCommand(command: string | undefined): boolean {
+  if (!command) return false;
+  const sub = parseParallCliInvocation(command);
+  return sub?.[0] === "no-reply";
+}

package/src/event-format.ts

@@ -25,6 +25,15 @@ export function buildEventBody(event: ParallEvent): string {
       }
     }
     lines.push("", event.body);
+  } else if (event.type === "task_comment") {
+    lines.push(`[Event: task.comment.created]`);
+    const taskLabel = event.targetName
+      ? `${event.targetName} (prll://${event.targetId})`
+      : `prll://${event.targetId}`;
+    lines.push(`[Task: ${taskLabel}]`);
+    lines.push(`[From: ${event.senderName} (prll://${event.senderId})]`);
+    lines.push(`[Comment ID: prll://${event.messageId}]`);
+    lines.push("", event.body);
   } else {
     lines.push(`[Event: task.assigned]`);
     const taskLabel = event.targetName

package/src/gateway-base.ts

@@ -7,6 +7,8 @@ import type {
   AgentConfigUpdateData,
   Chat,
   ChatUpdateData,
+  Comment,
+  DispatchNewData,
   HelloData,
   MessageNewData,
   Task,
@@ -222,6 +224,19 @@ export class ParallAgentGateway {
       }
     });
 
+    ws.on("dispatch.new", async (data: DispatchNewData) => {
+      if (data.event_type !== "task_comment") return;
+      if (!data.source_id || !data.task_id) return;
+      try {
+        const dispatched = await this.handleTaskComment(data.source_id, data.task_id, data.actor_id);
+        if (dispatched) {
+          this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+        }
+      } catch (err) {
+        this.opts.log?.error(`parall[${this.opts.accountId}]: task comment dispatch failed for ${data.source_id}: ${String(err)}`);
+      }
+    });
+
     this.opts.log?.info(`parall[${this.opts.accountId}]: connecting to ${this.opts.connectionLabel ?? "Parall WS"}...`);
     await ws.connect();
 
@@ -299,8 +314,8 @@ export class ParallAgentGateway {
         target_type: target.target_type,
         target_id: target.target_id,
         content: {
-          trigger_type: event.type === "task" ? "task_assign" : "mention",
-          trigger_ref: event.type === "task" ? { task_id: event.targetId } : { message_id: event.messageId },
+          trigger_type: event.type === "task" ? "task_assign" : event.type === "task_comment" ? "task_comment" : "mention",
+          trigger_ref: event.type === "task" ? { task_id: event.targetId } : event.type === "task_comment" ? { comment_id: event.messageId, task_id: event.targetId } : { message_id: event.messageId },
           sender_id: event.senderId,
           sender_name: event.senderName,
           summary: event.body.substring(0, 200),
@@ -798,6 +813,75 @@ export class ParallAgentGateway {
     return dispatched;
   }
 
+  private async handleTaskComment(commentId: string, taskId: string, actorId: string | null): Promise<boolean> {
+    const dedupeKey = `comment:${commentId}`;
+    if (this.dispatchedTasks.has(dedupeKey)) return false;
+    this.dispatchedTasks.add(dedupeKey);
+
+    let comment: Comment | null = null;
+    try {
+      comment = await this.opts.client.getComment(this.opts.config.org_id, commentId);
+    } catch (err: unknown) {
+      const status = (err as { status?: number })?.status;
+      if (status === 404) {
+        // Comment deleted — ack stale dispatch so it doesn't pile up.
+        this.opts.log?.info(`parall[${this.opts.accountId}]: skipping deleted comment ${commentId}, acking stale dispatch`);
+        this.dispatchedTasks.delete(dedupeKey);
+        return true; // caller will ack
+      }
+      this.dispatchedTasks.delete(dedupeKey);
+      return false; // transient error — leave pending for retry
+    }
+    if (!comment) {
+      this.dispatchedTasks.delete(dedupeKey);
+      return true; // null response = gone, ack stale dispatch
+    }
+
+    let task: Task | null = null;
+    try {
+      task = await this.opts.client.getTask(this.opts.config.org_id, taskId);
+    } catch { /* task context is optional */ }
+
+    const taskLabel = task ? `${task.identifier ?? task.id} "${task.title}"` : taskId;
+    this.opts.log?.info(`parall[${this.opts.accountId}]: task comment on ${taskLabel} by ${actorId ?? "unknown"}`);
+
+    const parts: string[] = [];
+    if (task) {
+      parts.push(`Task: ${task.title} (prll://${task.id})`);
+      parts.push(`Status: ${task.status}`, `Priority: ${task.priority}`);
+    } else {
+      parts.push(`Task: prll://${taskId}`);
+    }
+    parts.push(`Comment by: ${comment.author?.display_name ?? actorId ?? "unknown"} (prll://${comment.author_id})`);
+    parts.push("", comment.body);
+
+    const event: ParallEvent = {
+      type: "task_comment",
+      targetId: taskId,
+      targetName: task?.identifier ?? undefined,
+      targetType: "task",
+      senderId: comment.author_id,
+      senderName: comment.author?.display_name ?? actorId ?? "unknown",
+      messageId: commentId,
+      body: parts.join("\n"),
+      ackSourceType: "comment",
+      ackSourceId: commentId,
+    };
+
+    let dispatched: boolean;
+    try {
+      dispatched = await this.handleInboundEvent(event);
+    } catch (err) {
+      // Clear dedupe key so the event remains retryable on next catch-up.
+      this.dispatchedTasks.delete(dedupeKey);
+      throw err;
+    }
+    if (!dispatched) {
+      this.dispatchedTasks.delete(dedupeKey);
+    }
+    return dispatched;
+  }
+
   private async catchUpFromDispatch(coldStart = false) {
     const minAge = coldStart ? Date.now() - this.COLD_START_WINDOW_MS : 0;
     let cursor: string | undefined;
@@ -845,6 +929,8 @@ export class ParallAgentGateway {
             } else {
               dispatched = true;
             }
+          } else if (item.event_type === "task_comment" && item.source_id && item.task_id) {
+            dispatched = await this.handleTaskComment(item.source_id, item.task_id, item.actor_id);
           } else if (item.event_type === "message" && item.source_id && item.chat_id) {
             if (!this.tryClaimMessage(item.source_id)) continue;
             let msg: Awaited<ReturnType<typeof this.opts.client.getMessage>> | null = null;

package/src/index.ts

@@ -3,5 +3,6 @@ export * from "./session-state.js";
 export * from "./routing.js";
 export * from "./event-format.js";
 export * from "./prompt-fragments.js";
+export * from "./bridge-workspace.js";
 export * from "./dispatch-adapter.js";
 export * from "./gateway-base.js";

package/src/types.ts

@@ -16,7 +16,7 @@ export type DispatchState = {
 
 /** Normalized inbound event from Parall. */
 export type ParallEvent = {
-  type: "message" | "task";
+  type: "message" | "task" | "task_comment";
   targetId: string;
   targetName?: string;
   targetType?: string;
@@ -32,6 +32,6 @@ export type ParallEvent = {
     fileSize: number;
     mimeType: string;
   }>;
-  ackSourceType?: "message" | "task_activity";
+  ackSourceType?: "message" | "task_activity" | "comment";
   ackSourceId?: string;
 };