@parall/parall 1.12.0

package/src/hooks.ts

@@ -0,0 +1,162 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { extractAccountIdFromSessionKey } from "./session.js";
+import { clearDispatchGroupKey, clearDispatchMessageId, clearSessionMessageId, getDispatchGroupKey, getDispatchMessageId, getParallAccountState, getSessionChatId } from "./runtime.js";
+
+/**
+ * Resolve the ParallClient + orgId + sessionId for a hook context.
+ * Returns undefined if the account/session is not active.
+ */
+function resolveClientForHook(sessionKey: string | undefined) {
+  if (!sessionKey) return undefined;
+  const chatId = getSessionChatId(sessionKey);
+  if (!chatId) return undefined;
+  const accountId = extractAccountIdFromSessionKey(sessionKey);
+  if (!accountId) return undefined;
+
+  const state = getParallAccountState(accountId);
+  if (!state) return undefined;
+
+  return { ...state, chatId, sessionId: state.activeSessionId };
+}
+
+const PRLL_CHANNEL_CONTEXT = `## Parall Channel — Message Delivery
+
+Messages from the Parall channel arrive as \`[Event: ...]\` blocks.
+Your text output is **not delivered to the user** — it is discarded silently.
+To reply, you **must** use the Parall CLI via the exec (Bash) tool.
+
+Each event includes \`[Chat: ... (cht_xxx)]\` — use that chat ID to reply:
+
+    npx @parall/cli@latest messages send cht_xxx --text "Your reply here"
+
+Credentials are pre-configured in every Bash command — no setup needed.
+Load the \`parall-platform\` skill for full CLI reference.
+When an event has \`[Hint: no_reply]\`, do not reply to that specific event.
+A dispatch may contain multiple events — only skip replies to the hinted ones.`;
+
+export function registerParallHooks(api: OpenClawPluginApi) {
+  const log = api.logger;
+
+  // Append Parall channel context AFTER workspace files so it takes precedence
+  api.on("before_prompt_build", () => {
+    return { appendSystemContext: PRLL_CHANNEL_CONTEXT };
+  });
+
+  // before_tool_call -> (1) await step creation to get step ID, (2) ENV injection for exec tool
+  api.on("before_tool_call", async (event, ctx) => {
+    const sessionKey = ctx.sessionKey;
+
+    // (1) Create tool_call step and await to get step ID
+    let stepId: string | undefined;
+    const resolved = resolveClientForHook(sessionKey);
+    if (resolved?.sessionId && event.toolCallId) {
+      const groupKey = sessionKey ? getDispatchGroupKey(sessionKey) : undefined;
+      try {
+        const step = await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.sessionId, {
+          step_type: "tool_call",
+          target_type: resolved.chatId.startsWith("cht_") ? "chat" : resolved.chatId.startsWith("tsk_") ? "task" : "",
+          target_id: resolved.chatId || undefined,
+          content: {
+            call_id: event.toolCallId,
+            tool_name: event.toolName,
+            tool_input: event.params ?? {},
+            status: "running",
+            started_at: new Date().toISOString(),
+          },
+          group_key: groupKey,
+          runtime_key: event.toolCallId,
+        });
+        stepId = step.id;
+      } catch (err) {
+        log?.warn(`parall hook before_tool_call failed: ${String(err)}`);
+      }
+    }
+
+    // (2) ENV injection — only for the exec (Bash) tool
+    if (event.toolName !== "exec") return;
+    if (!sessionKey) return;
+    const accountId = extractAccountIdFromSessionKey(sessionKey);
+    if (!accountId) return;
+    const state = getParallAccountState(accountId);
+    if (!state) return;
+
+    // Dynamic per-dispatch context (changes each dispatch)
+    const chatId = getSessionChatId(sessionKey);
+    const triggerMsgId = getDispatchMessageId(sessionKey);
+
+    const injectedEnv: Record<string, string> = {};
+    if (state.activeSessionId) injectedEnv.PRLL_SESSION_ID = state.activeSessionId;
+    if (stepId) injectedEnv.PRLL_STEP_ID = stepId;
+    if (chatId) injectedEnv.PRLL_CHAT_ID = chatId;
+    if (triggerMsgId) injectedEnv.PRLL_TRIGGER_MESSAGE_ID = triggerMsgId;
+    if (state.wikiMountRoot) injectedEnv.PRLL_WIKI_MOUNT_ROOT = state.wikiMountRoot;
+
+    // OpenClaw context (upstream doesn't inject these into exec env yet)
+    injectedEnv.OPENCLAW_SESSION_KEY = sessionKey;
+    if (event.toolCallId) injectedEnv.OPENCLAW_TOOL_CALL_ID = event.toolCallId;
+
+    // Shallow merge — preserve agent's original env params
+    const existingEnv = (event.params as Record<string, unknown>)?.env as Record<string, string> | undefined;
+
+    return {
+      params: {
+        env: { ...existingEnv, ...injectedEnv },
+      },
+    };
+  });
+
+  // after_tool_call -> send tool_result step to AgentSession
+  api.on("after_tool_call", async (event, ctx) => {
+    const resolved = resolveClientForHook(ctx.sessionKey);
+    if (!resolved?.sessionId || !event.toolCallId) return;
+    try {
+      await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.sessionId, {
+        step_type: "tool_result",
+        target_type: resolved.chatId.startsWith("cht_") ? "chat" : resolved.chatId.startsWith("tsk_") ? "task" : "",
+        target_id: resolved.chatId || undefined,
+        content: {
+          call_id: event.toolCallId,
+          tool_name: event.toolName,
+          status: event.error ? "error" : "success",
+          output: event.error ?? (typeof event.result === "string" ? event.result : JSON.stringify(event.result ?? "")),
+          duration_ms: event.durationMs ?? 0,
+          collapsible: true,
+        },
+      });
+    } catch (err) {
+      log?.warn(`parall hook after_tool_call failed: ${String(err)}`);
+    }
+  });
+
+  // agent_end -> end of a dispatch cycle, NOT end of session.
+  // Session lives across dispatches — don't update session status here.
+  // On error: emit a visible error step so the chat user sees the failure.
+  api.on("agent_end", async (event, ctx) => {
+    // Emit error step if the dispatch failed
+    if (event.error && ctx.sessionKey) {
+      const accountId = extractAccountIdFromSessionKey(ctx.sessionKey);
+      const state = accountId ? getParallAccountState(accountId) : undefined;
+      const chatId = getSessionChatId(ctx.sessionKey);
+      if (state?.activeSessionId && chatId) {
+        try {
+          await state.client.createAgentStep(state.orgId, state.agentUserId, state.activeSessionId, {
+            step_type: "text",
+            target_type: "chat",
+            target_id: chatId,
+            content: { text: `Dispatch failed: ${String(event.error)}`, suppressed: false },
+            projection: true,
+          });
+        } catch (err) {
+          log?.warn(`parall hook agent_end: failed to emit error step: ${String(err)}`);
+        }
+      }
+    }
+
+    // Clean up dispatch-specific state
+    if (ctx.sessionKey) {
+      clearSessionMessageId(ctx.sessionKey);
+      clearDispatchMessageId(ctx.sessionKey);
+      clearDispatchGroupKey(ctx.sessionKey);
+    }
+  });
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/core";
+import { parallPlugin } from "./channel.js";
+import { setParallRuntime } from "./runtime.js";
+import { registerParallHooks } from "./hooks.js";
+
+const plugin = {
+  id: "parall",
+  name: "Parall",
+  description: "Parall IM channel plugin — Agent-Native messaging with tool call visualization.",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setParallRuntime(api.runtime);
+    api.registerChannel({ plugin: parallPlugin });
+    registerParallHooks(api);
+  },
+};
+
+export default plugin;

package/src/outbound.ts

@@ -0,0 +1,37 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+
+/** Extract ChannelOutboundAdapter from ChannelPlugin (removed from public SDK exports in 2026.3.24). */
+type ChannelOutboundAdapter = NonNullable<ChannelPlugin["outbound"]>;
+import { resolveParallAccount } from "./accounts.js";
+import { getParallAccountState } from "./runtime.js";
+import { ParallClient } from "@parall/sdk";
+import type { SendMessageRequest } from "@parall/sdk";
+
+export const parallOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  textChunkLimit: 10000,
+  chunker: null,
+
+  sendText: async ({ cfg, to, text, accountId }) => {
+    const account = resolveParallAccount({ cfg, accountId: accountId ?? undefined });
+    if (!account.enabled) throw new Error("Parall account is disabled");
+    if (!account.configured) throw new Error("Parall account is not configured: parall_url/api_key/org_id required");
+
+    const state = getParallAccountState(account.accountId);
+    const client = state?.client ?? new ParallClient({
+      baseUrl: account.config.parall_url,
+      token: account.config.api_key,
+    });
+    const orgId = state?.orgId ?? account.config.org_id;
+    const chatId = to;
+
+    // Outbound path has no step context — send without agent_step_id.
+    // Step linkage happens via the CLI's ENV-injected PRLL_STEP_ID in the normal dispatch path.
+    const req: SendMessageRequest = {
+      message_type: "text",
+      content: { text },
+    };
+    const msg = await client.sendMessage(orgId, chatId, req);
+    return { channel: "parall", messageId: msg.id, channelId: chatId };
+  },
+};

package/src/routing.ts

@@ -0,0 +1,48 @@
+import type { ParallEvent, DispatchState } from "./runtime.js";
+
+/** Where an inbound event should be routed. */
+export type TriggerDisposition =
+  | { action: "main" }
+  | { action: "buffer-main" }
+  | { action: "buffer-fork"; forkKey: string }
+  | { action: "new-fork" };
+
+/** Pluggable strategy for routing triggers when main session is busy. */
+export type RoutingStrategy = (event: ParallEvent, state: DispatchState) => TriggerDisposition;
+
+const MAX_CONCURRENT_FORKS = 20;
+
+/**
+ * Default routing strategy:
+ * - Same target as main → buffer-main (strict per-target serial ordering)
+ * - Active fork for same target → buffer into that fork
+ * - Too many forks → buffer-main (backpressure)
+ * - Otherwise → create a new fork
+ */
+export const defaultRoutingStrategy: RoutingStrategy = (event, state) => {
+  // P0: same target as main must stay serial — fork would see stale transcript
+  if (state.mainCurrentTargetId === event.targetId) {
+    return { action: "buffer-main" };
+  }
+
+  // Same target already has a fork → buffer into it
+  const existingForkKey = state.activeForks.get(event.targetId);
+  if (existingForkKey) return { action: "buffer-fork", forkKey: existingForkKey };
+
+  // Backpressure: cap concurrent forks to avoid unbounded fan-out
+  if (state.activeForks.size >= MAX_CONCURRENT_FORKS) {
+    return { action: "buffer-main" };
+  }
+
+  return { action: "new-fork" };
+};
+
+/** Route an inbound event based on current dispatch state. */
+export function routeTrigger(
+  event: ParallEvent,
+  state: DispatchState,
+  strategy: RoutingStrategy = defaultRoutingStrategy,
+): TriggerDisposition {
+  if (!state.mainDispatching) return { action: "main" };
+  return strategy(event, state);
+}

package/src/runtime.ts

@@ -0,0 +1,135 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { ParallClient, ParallWs } from "@parall/sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setParallRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getParallRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Parall runtime not initialized");
+  }
+  return runtime;
+}
+
+// Cached client state per account, populated by gateway.ts startAccount
+export type ParallAccountState = {
+  client: ParallClient;
+  orgId: string;
+  agentUserId: string;
+  activeSessionId?: string;
+  wikiMountRoot?: string;
+  ws?: ParallWs;
+  orchestratorSessionKey?: string;
+};
+
+const accountStates = new Map<string, ParallAccountState>();
+
+export function setParallAccountState(accountId: string, state: ParallAccountState) {
+  accountStates.set(accountId, state);
+}
+
+export function removeParallAccountState(accountId: string) {
+  accountStates.delete(accountId);
+}
+
+export function getParallAccountState(accountId: string): ParallAccountState | undefined {
+  return accountStates.get(accountId);
+}
+
+export function getAllParallAccountStates(): ReadonlyMap<string, ParallAccountState> {
+  return new Map(accountStates);
+}
+
+// Session key → original chat ID mapping.
+// OpenClaw normalizes session keys to lowercase, but Parall IDs are case-sensitive.
+const sessionChatIdMap = new Map<string, string>();
+const sessionMessageIdMap = new Map<string, string>();
+// Per-dispatch snapshot: message ID captured when a dispatch starts, immune to later overwrites.
+// Keyed by lowercased session key, cleared when the agent run ends.
+const dispatchMessageIdMap = new Map<string, string>();
+
+export function setSessionChatId(sessionKey: string, chatId: string) {
+  sessionChatIdMap.set(sessionKey.toLowerCase(), chatId);
+}
+
+export function getSessionChatId(sessionKey: string): string | undefined {
+  return sessionChatIdMap.get(sessionKey.toLowerCase());
+}
+
+export function setSessionMessageId(sessionKey: string, messageId: string) {
+  sessionMessageIdMap.set(sessionKey.toLowerCase(), messageId);
+}
+
+export function getSessionMessageId(sessionKey: string): string | undefined {
+  return sessionMessageIdMap.get(sessionKey.toLowerCase());
+}
+
+export function clearSessionMessageId(sessionKey: string) {
+  sessionMessageIdMap.delete(sessionKey.toLowerCase());
+}
+
+/** Snapshot the message ID at dispatch time — immune to later session-level overwrites. */
+export function setDispatchMessageId(sessionKey: string, messageId: string) {
+  dispatchMessageIdMap.set(sessionKey.toLowerCase(), messageId);
+}
+
+/** Read the dispatch-time snapshot. Prefer this over getSessionMessageId for provenance. */
+export function getDispatchMessageId(sessionKey: string): string | undefined {
+  return dispatchMessageIdMap.get(sessionKey.toLowerCase());
+}
+
+export function clearDispatchMessageId(sessionKey: string) {
+  dispatchMessageIdMap.delete(sessionKey.toLowerCase());
+}
+
+// Per-dispatch group key — shared between thinking + tool_call steps for Session Panel grouping.
+// Set per LLM response turn in gateway.ts, read in hooks.ts.
+const dispatchGroupKeyMap = new Map<string, string>();
+
+export function setDispatchGroupKey(sessionKey: string, groupKey: string) {
+  dispatchGroupKeyMap.set(sessionKey.toLowerCase(), groupKey);
+}
+
+export function getDispatchGroupKey(sessionKey: string): string | undefined {
+  return dispatchGroupKeyMap.get(sessionKey.toLowerCase());
+}
+
+export function clearDispatchGroupKey(sessionKey: string) {
+  dispatchGroupKeyMap.delete(sessionKey.toLowerCase());
+}
+
+/** Result from a completed fork dispatch, to be injected into main session's next turn. */
+export type ForkResult = {
+  forkSessionKey: string;
+  sourceEvent: { type: string; targetId: string; summary: string };
+  actions: string[];  // human-readable list of actions taken (e.g. "replied to cht_xxx")
+};
+
+/** Mutable dispatch state for the orchestrator gateway. Per-account, managed by gateway.ts. */
+export type DispatchState = {
+  mainDispatching: boolean;
+  /** The targetId currently being processed by main. Used to enforce per-target serial ordering. */
+  mainCurrentTargetId?: string;
+  /** targetId → fork session key. One active fork per target at most. */
+  activeForks: Map<string, string>;
+  pendingForkResults: ForkResult[];
+  mainBuffer: ParallEvent[];
+};
+
+/** Normalized inbound event from Parall. */
+export type ParallEvent = {
+  type: "message" | "task";
+  targetId: string;       // chatId or taskId
+  targetName?: string;
+  targetType?: string;    // "direct" | "group" | "task"
+  senderId: string;
+  senderName: string;
+  messageId: string;
+  body: string;           // raw message text or task description
+  threadRootId?: string;
+  noReply?: boolean;
+  mediaFields?: Record<string, string | undefined>;
+};

package/src/session.ts

@@ -0,0 +1,36 @@
+const PRLL_SESSION_PREFIX = "agent:main:parall:";
+
+/** Build OpenClaw session key from Parall account, chat type, and chat ID. */
+export function buildSessionKey(accountId: string, chatType: string, chatId: string): string {
+  return `${PRLL_SESSION_PREFIX}${accountId}:${chatType}:${chatId}`;
+}
+
+/**
+ * Extract account ID from an OpenClaw session key.
+ * Format: "agent:main:parall:{accountId}:{type}:{chatId}"
+ */
+export function extractAccountIdFromSessionKey(sessionKey: string | undefined): string | undefined {
+  if (!sessionKey?.startsWith(PRLL_SESSION_PREFIX)) return undefined;
+  const rest = sessionKey.slice(PRLL_SESSION_PREFIX.length);
+  const firstColon = rest.indexOf(":");
+  if (firstColon < 0) return undefined;
+  return rest.slice(0, firstColon) || undefined;
+}
+
+/**
+ * Extract chat ID from an OpenClaw session key.
+ * Format: "agent:main:parall:{accountId}:{type}:{chatId}"
+ */
+export function extractChatIdFromSessionKey(sessionKey: string | undefined): string | undefined {
+  if (!sessionKey?.startsWith(PRLL_SESSION_PREFIX)) return undefined;
+  const rest = sessionKey.slice(PRLL_SESSION_PREFIX.length);
+  // Skip accountId and chatType segments
+  const parts = rest.split(":");
+  if (parts.length < 3) return undefined;
+  return parts.slice(2).join(":") || undefined;
+}
+
+/** Build the single orchestrator session key for all Parall events. */
+export function buildOrchestratorSessionKey(accountId: string): string {
+  return `${PRLL_SESSION_PREFIX}${accountId}:orchestrator`;
+}

package/src/types.ts

@@ -0,0 +1,18 @@
+export type ParallChannelConfig = {
+  enabled?: boolean;
+  /** Parall server URL, e.g. "https://parall.example.com" */
+  parall_url: string;
+  /** Agent API key (agk_xxx) */
+  api_key: string;
+  /** Organization ID */
+  org_id: string;
+  /** WS Gateway URL (defaults to parall_url with ws:// scheme + /ws path) */
+  ws_url?: string;
+};
+
+export type ResolvedParallAccount = {
+  accountId: string;
+  enabled: boolean;
+  configured: boolean;
+  config: ParallChannelConfig;
+};

package/src/wiki-helper.ts

@@ -0,0 +1,157 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+
+type Logger = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+type StartWikiHelperParams = {
+  accountId: string;
+  parallUrl: string;
+  apiKey: string;
+  orgId: string;
+  agentId: string;
+  stateDir: string;
+  log?: Logger;
+};
+
+type WikiHelperRuntime = {
+  mountRoot: string;
+  stop: () => void;
+};
+
+const DEFAULT_SYNC_TIMEOUT_MS = 30_000;
+const DEFAULT_WATCH_INTERVAL_SEC = 30;
+
+function isCommandMissing(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+function resolveMountRoot(stateDir: string): string {
+  return process.env.PRLL_WIKI_MOUNT_ROOT?.trim() || path.join(stateDir, "workspace");
+}
+
+function resolveWatchIntervalSec(): number {
+  const raw = process.env.PRLL_WIKI_REFRESH_INTERVAL_SEC?.trim();
+  if (!raw) {
+    return DEFAULT_WATCH_INTERVAL_SEC;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_WATCH_INTERVAL_SEC;
+}
+
+function buildWikiHelperEnv(params: StartWikiHelperParams, mountRoot: string): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    PRLL_API_URL: params.parallUrl,
+    PRLL_API_KEY: params.apiKey,
+    PRLL_ORG_ID: params.orgId,
+    PRLL_AGENT_ID: params.agentId,
+    PRLL_WIKI_MOUNT_ROOT: mountRoot,
+  };
+}
+
+async function runWikiSync(params: StartWikiHelperParams, env: NodeJS.ProcessEnv): Promise<"ok" | "missing" | "failed"> {
+  return new Promise((resolve) => {
+    let timedOut = false;
+    let settled = false;
+
+    const child = spawn("parall", ["wiki", "sync"], {
+      env,
+      stdio: "ignore",
+    });
+
+    const settle = (value: "ok" | "missing" | "failed") => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      params.log?.warn?.(`parall[${params.accountId}]: parall sync timed out after ${DEFAULT_SYNC_TIMEOUT_MS}ms`);
+      child.kill("SIGTERM");
+      setTimeout(() => child.kill("SIGKILL"), 5_000).unref();
+    }, DEFAULT_SYNC_TIMEOUT_MS);
+    timer.unref();
+
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      if (isCommandMissing(error)) {
+        params.log?.warn?.(`parall[${params.accountId}]: parall not installed, skipping wiki auto-sync/watch`);
+        settle("missing");
+        return;
+      }
+      params.log?.warn?.(`parall[${params.accountId}]: parall sync failed to start: ${String(error)}`);
+      settle("failed");
+    });
+
+    child.on("exit", (code, signal) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        settle("failed");
+        return;
+      }
+      if (code === 0) {
+        params.log?.info?.(`parall[${params.accountId}]: parall sync completed`);
+        settle("ok");
+        return;
+      }
+      params.log?.warn?.(
+        `parall[${params.accountId}]: parall sync exited with code=${code ?? "null"} signal=${signal ?? "null"}`,
+      );
+      settle("failed");
+    });
+  });
+}
+
+export async function startWikiHelper(params: StartWikiHelperParams): Promise<WikiHelperRuntime> {
+  const mountRoot = resolveMountRoot(params.stateDir);
+  const env = buildWikiHelperEnv(params, mountRoot);
+
+  const syncResult = await runWikiSync(params, env);
+  if (syncResult === "missing") {
+    return {
+      mountRoot,
+      stop() {},
+    };
+  }
+
+  const intervalSec = resolveWatchIntervalSec();
+  let stopped = false;
+  const watch = spawn("parall", ["wiki", "watch", "--interval-sec", String(intervalSec)], {
+    env,
+    stdio: "ignore",
+  });
+
+  watch.on("error", (error) => {
+    if (stopped) return;
+    if (isCommandMissing(error)) {
+      params.log?.warn?.(`parall[${params.accountId}]: parall disappeared before watch could start`);
+      return;
+    }
+    params.log?.warn?.(`parall[${params.accountId}]: parall watch failed: ${String(error)}`);
+  });
+
+  watch.on("exit", (code, signal) => {
+    if (stopped) return;
+    params.log?.warn?.(
+      `parall[${params.accountId}]: parall watch exited with code=${code ?? "null"} signal=${signal ?? "null"}`,
+    );
+  });
+
+  params.log?.info?.(`parall[${params.accountId}]: parall watch started (interval=${intervalSec}s)`);
+
+  return {
+    mountRoot,
+    stop() {
+      stopped = true;
+      if (watch.exitCode === null && watch.signalCode === null) {
+        watch.kill("SIGTERM");
+        setTimeout(() => watch.kill("SIGKILL"), 5_000).unref();
+      }
+    },
+  };
+}