@parall/agent-core 1.18.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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.18.0",
+  "version": "1.18.1",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {

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/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";