@parall/parall 1.12.0

package/openclaw.plugin.json

@@ -0,0 +1,14 @@
+{
+  "id": "parall",
+  "channels": ["parall"],
+  "skills": [
+    "./skills/parall-wiki",
+    "./skills/parall-tasks",
+    "./skills/parall-platform"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@parall/parall",
+  "version": "1.12.0",
+  "description": "OpenClaw channel plugin for Parall IM",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/parall-hq/parall-mono",
+    "directory": "ts/openclaw-channel"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "skills",
+    "openclaw.plugin.json"
+  ],
+  "dependencies": {
+    "@parall/sdk": "1.12.0",
+    "@parall/cli": "1.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "openclaw": "2026.4.2",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "openclaw": ">=2026.4.2"
+  },
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "install": {
+      "minHostVersion": ">=2026.4.2"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/skills/parall-platform/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: parall-platform
+description: "Parall platform queries: list org members, agents, chats, read message history, check identity. Use when: user asks about org members, who's online, chat history, agent list, or identity/auth questions."
+---
+
+# Parall Platform
+
+Query organization data via the Parall CLI. Auth is pre-configured.
+
+## Identity
+
+```bash
+npx @parall/cli@latest whoami
+```
+
+## Members & Agents
+
+```bash
+npx @parall/cli@latest members list          # All org members (humans + agents)
+npx @parall/cli@latest agents list           # Agents only
+npx @parall/cli@latest users get usr_xxx     # Get user details by ID
+```
+
+## Chats & Messages
+
+```bash
+npx @parall/cli@latest chats list            # List all chats
+npx @parall/cli@latest messages list cht_xxx # Read chat message history
+```
+
+## Sending Messages
+
+Each `[Event: message.new]` includes `[Chat: ... (cht_xxx)]` — always use that chat ID explicitly.
+
+```bash
+# Reply to a chat (use the chat ID from the event)
+npx @parall/cli@latest messages send cht_xxx --text "Your reply"
+
+# Direct message by user ID or display name
+npx @parall/cli@latest dm usr_xxx --text "Hello"
+npx @parall/cli@latest dm "Alice" --text "Hello"
+
+# Thread reply
+npx @parall/cli@latest messages send cht_xxx --text "Reply" --thread-root-id 01JWC...
+
+# FYI message (no response expected)
+npx @parall/cli@latest messages send cht_xxx --text "FYI: done" --no-reply
+```
+
+All CLI output is JSON.

package/skills/parall-tasks/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: parall-tasks
+description: "Parall task operations: create, update, comment on, and query tasks and projects. Use when: user asks to create a task, update task status, add comments, list tasks, or manage projects."
+---
+
+# Parall Tasks
+
+Manage tasks and projects via the Parall CLI. Auth and runtime context are pre-configured.
+
+## Task Commands
+
+```bash
+# List tasks (filterable by status)
+npx @parall/cli@latest tasks list
+npx @parall/cli@latest tasks list --status todo
+npx @parall/cli@latest tasks list --status in_progress
+
+# Create a task
+npx @parall/cli@latest tasks create --title "Task title" [--assignee-id usr_xxx] [--project-id prj_xxx]
+
+# Update task status
+npx @parall/cli@latest tasks update tsk_xxx --status in_progress
+npx @parall/cli@latest tasks update tsk_xxx --status done
+
+# Add a comment
+npx @parall/cli@latest tasks comments add tsk_xxx --body "Progress update..."
+```
+
+## Project Commands
+
+```bash
+npx @parall/cli@latest projects list
+```
+
+## Responding to Task Assignments
+
+When you receive `[Event: task.assigned]`:
+
+1. Acknowledge with a comment: `tasks comments add tsk_xxx --body "On it"`
+2. Update status: `tasks update tsk_xxx --status in_progress`
+3. Do the work
+4. Report results via comment and update status to `done`
+
+All CLI output is JSON.

package/skills/parall-wiki/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: parall-wiki
+description: "Parall wiki operations: read, search, edit, and propose changes to organization knowledge bases. Use when: user asks to read/write docs, edit wiki pages, search knowledge base, propose changes, or review changesets."
+---
+
+# Parall Wiki
+
+Manage organization wikis via the Parall CLI. Auth is pre-configured.
+
+## Browsing (no local state needed)
+
+```bash
+npx @parall/cli@latest wiki list                       # List all wikis
+npx @parall/cli@latest wiki tree <slug>                 # List files and directories
+npx @parall/cli@latest wiki tree <slug> --path docs/    # List a subdirectory
+```
+
+## Editing
+
+Wiki editing works on a **local workspace** — a directory on disk where wiki
+files are synced. You sync from the server, edit files locally, then propose
+a changeset.
+
+### Step 1: Sync
+
+```bash
+npx @parall/cli@latest wiki sync <slug>
+```
+
+This downloads wiki files to a local directory. The output includes the
+**absolute mount path** for each wiki (e.g. `synced → /data/.openclaw/workspace/kb`).
+
+### Step 2: Find the mount path
+
+The sync output JSON contains `synced[].path` — the absolute path where files
+live. You can also check it anytime with:
+
+```bash
+npx @parall/cli@latest wiki status <slug>
+```
+
+The output includes `Mount: /absolute/path/to/<slug>`.
+
+Use this path with `read`, `write`, and `edit` tools. For example, if the mount
+is `/data/.openclaw/workspace/kb`, then `README.md` is at
+`/data/.openclaw/workspace/kb/README.md`.
+
+### Step 3: Edit files
+
+Use standard file tools (`read`, `write`, `edit`) on files under the mount path.
+
+### Step 4: Review changes
+
+```bash
+npx @parall/cli@latest wiki diff <slug>       # Shows unified diff of all local changes
+npx @parall/cli@latest wiki status <slug>     # Shows which files changed with +/- line counts
+```
+
+Always review before proposing.
+
+### Step 5: Propose changeset
+
+```bash
+npx @parall/cli@latest wiki changeset create <slug> --title "Description of changes"
+```
+
+This uploads your local changes as a changeset for review.
+
+## Changeset Management
+
+```bash
+npx @parall/cli@latest wiki changeset list <slug>               # List all changesets
+npx @parall/cli@latest wiki changeset show <changesetId> <slug> # Show detail + feedback
+npx @parall/cli@latest wiki changeset diff <changesetId> <slug> # Show changeset diff
+```
+
+If a changeset is rejected, fix the files locally and re-propose:
+
+```bash
+npx @parall/cli@latest wiki changeset create <slug> --update <changesetId>
+```
+
+The title is inherited from the original changeset — no need to repeat it.
+
+## Discarding local changes
+
+```bash
+npx @parall/cli@latest wiki reset <slug>      # Restore all files to last synced state
+```
+
+## History
+
+```bash
+npx @parall/cli@latest wiki log <slug>        # Recent wiki operations
+```
+
+All CLI output is JSON. Run `npx @parall/cli@latest wiki --help` for full options.

package/src/accounts.ts

@@ -0,0 +1,38 @@
+import type { ResolvedParallAccount, ParallChannelConfig } from "./types.js";
+
+const DEFAULT_ACCOUNT_ID = "default";
+
+type OpenClawConfig = Record<string, unknown>;
+
+function readParallConfig(cfg: OpenClawConfig): ParallChannelConfig | undefined {
+  const channels = cfg.channels as Record<string, unknown> | undefined;
+  return channels?.parall as ParallChannelConfig | undefined;
+}
+
+export function listParallAccountIds(cfg: OpenClawConfig): string[] {
+  const parallCfg = readParallConfig(cfg);
+  if (!parallCfg) return [];
+  return [DEFAULT_ACCOUNT_ID];
+}
+
+export function resolveParallAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string;
+}): ResolvedParallAccount {
+  const { cfg, accountId = DEFAULT_ACCOUNT_ID } = params;
+  const parallCfg = readParallConfig(cfg);
+  const config: ParallChannelConfig = {
+    parall_url: parallCfg?.parall_url ?? "",
+    api_key: parallCfg?.api_key ?? "",
+    org_id: parallCfg?.org_id ?? "",
+    ws_url: parallCfg?.ws_url,
+    enabled: parallCfg?.enabled,
+  };
+  const configured = Boolean(config.api_key && config.parall_url && config.org_id);
+  return {
+    accountId,
+    enabled: config.enabled !== false,
+    configured,
+    config,
+  };
+}

package/src/channel.ts

@@ -0,0 +1,40 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+import { listParallAccountIds, resolveParallAccount } from "./accounts.js";
+import { parallGateway } from "./gateway.js";
+import { parallOutbound } from "./outbound.js";
+import type { ResolvedParallAccount } from "./types.js";
+
+const meta: ChannelPlugin["meta"] = {
+  id: "parall",
+  label: "Parall",
+  selectionLabel: "Parall IM",
+  docsPath: "/channels/parall",
+  blurb: "Agent-Native IM platform.",
+  order: 80,
+};
+
+export const parallPlugin: ChannelPlugin<ResolvedParallAccount> = {
+  id: "parall",
+  meta,
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    polls: false,
+    threads: false,
+    media: true,
+    reactions: false,
+    edit: false,
+    reply: false,
+  },
+  config: {
+    listAccountIds: (cfg) => listParallAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveParallAccount({ cfg, accountId: accountId ?? undefined }),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      enabled: account.enabled,
+      configured: account.configured,
+    }),
+  },
+  outbound: parallOutbound,
+  gateway: parallGateway,
+};

package/src/config-manager.ts

@@ -0,0 +1,154 @@
+import type { ParallClient } from "@parall/sdk";
+import type { PlatformConfigResponse } from "@parall/sdk";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+interface CachedPlatformConfig {
+  version: string;
+  config: Record<string, unknown>;
+  fetchedAt: string;
+}
+
+interface ConfigManagerOpts {
+  client: ParallClient;
+  stateDir: string;
+  configPath: string;
+  credentials: { api_key: string; parall_url: string };
+  log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
+}
+
+const CACHE_FILENAME = "parall-platform-config.json";
+
+/** Tool names are no longer registered — all operations go through CLI. */
+
+function cachePath(stateDir: string): string {
+  return path.join(stateDir, CACHE_FILENAME);
+}
+
+function loadCachedConfig(stateDir: string): CachedPlatformConfig | null {
+  try {
+    const raw = fs.readFileSync(cachePath(stateDir), "utf-8");
+    return JSON.parse(raw) as CachedPlatformConfig;
+  } catch {
+    return null;
+  }
+}
+
+function saveCachedConfig(stateDir: string, config: PlatformConfigResponse): void {
+  const cached: CachedPlatformConfig = {
+    version: config.version,
+    config: config.config,
+    fetchedAt: new Date().toISOString(),
+  };
+  const filePath = cachePath(stateDir);
+  const tmpPath = `${filePath}.tmp`;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(tmpPath, JSON.stringify(cached, null, 2), "utf-8");
+  fs.renameSync(tmpPath, filePath);
+}
+
+/**
+ * Deep-merge platform config into an existing openclaw.json file.
+ * Only overwrites `models.providers.parall` and `agents.defaults` sections;
+ * all other keys (user customizations, other providers) are preserved.
+ */
+function applyToOpenClawConfig(
+  configPath: string,
+  platformConfig: Record<string, unknown>,
+  credentials: { api_key: string; parall_url: string },
+): void {
+  let existing: Record<string, unknown> = {};
+  try {
+    const raw = fs.readFileSync(configPath, "utf-8");
+    existing = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    // File doesn't exist or is invalid — start fresh
+  }
+
+  // Deep-merge models.providers.parall (preserve existing fields, overlay platform, inject credentials)
+  const models = (existing.models ?? {}) as Record<string, unknown>;
+  const providers = (models.providers ?? {}) as Record<string, unknown>;
+  const existingParall = (providers.parall ?? {}) as Record<string, unknown>;
+  const platformModels = (platformConfig.models ?? {}) as Record<string, unknown>;
+  const platformProviders = (platformModels.providers ?? {}) as Record<string, unknown>;
+  const platformParall = (platformProviders.parall ?? {}) as Record<string, unknown>;
+
+  providers.parall = {
+    ...existingParall,
+    ...platformParall,
+    apiKey: credentials.api_key,
+  };
+  models.providers = providers;
+  existing.models = models;
+
+  // Deep-merge agents.defaults (preserve existing fields, overlay platform)
+  const platformAgents = (platformConfig.agents ?? {}) as Record<string, unknown>;
+  if (platformAgents.defaults !== undefined) {
+    const agents = (existing.agents ?? {}) as Record<string, unknown>;
+    const existingDefaults = (agents.defaults ?? {}) as Record<string, unknown>;
+    agents.defaults = {
+      ...existingDefaults,
+      ...(platformAgents.defaults as Record<string, unknown>),
+    };
+    existing.agents = agents;
+  }
+
+  // No plugin tools to allow — all operations go through CLI.
+
+  // Atomic write
+  const tmpPath = `${configPath}.tmp`;
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(tmpPath, JSON.stringify(existing, null, 2), "utf-8");
+  fs.renameSync(tmpPath, configPath);
+}
+
+/**
+ * Fetch platform config from the server, cache it (LKG), and apply to openclaw.json.
+ * Degrades gracefully: uses cached config on fetch failure, continues if neither is available.
+ */
+export async function fetchAndApplyPlatformConfig(opts: ConfigManagerOpts): Promise<void> {
+  const { client, stateDir, configPath, credentials, log } = opts;
+
+  // 1. Load cached config (LKG)
+  const cached = loadCachedConfig(stateDir);
+
+  // 2. Fetch from server (with version for 304)
+  let fresh: PlatformConfigResponse | null = null;
+  try {
+    fresh = await client.getPlatformConfig(cached?.version);
+  } catch (err) {
+    // Fetch failed — fall through to use cache
+    if (cached) {
+      log?.warn(`platform config fetch failed, using cached version ${cached.version}: ${String(err)}`);
+      applyToOpenClawConfig(configPath, cached.config, credentials);
+      return;
+    }
+    // No cache and fetch fails — degrade gracefully
+    log?.error(`platform config fetch failed and no cache available: ${String(err)}`);
+    return;
+  }
+
+  // 3. 304 — config unchanged
+  if (fresh === null) {
+    log?.info("platform config unchanged (304)");
+    if (cached) {
+      applyToOpenClawConfig(configPath, cached.config, credentials);
+    }
+    return;
+  }
+
+  // 4. Validate schema compatibility before accepting
+  const SUPPORTED_SCHEMA_VERSION = 1;
+  if (fresh.schema_version !== undefined && fresh.schema_version > SUPPORTED_SCHEMA_VERSION) {
+    log?.error(`platform config schema_version ${fresh.schema_version} is newer than supported (${SUPPORTED_SCHEMA_VERSION}), keeping current config`);
+    if (cached) {
+      applyToOpenClawConfig(configPath, cached.config, credentials);
+    }
+    return;
+  }
+
+  // 5. Newer config received — save cache and apply
+  log?.info(`platform config updated to version ${fresh.version}`);
+  saveCachedConfig(stateDir, fresh);
+  applyToOpenClawConfig(configPath, fresh.config, credentials);
+}

package/src/fork.ts

@@ -0,0 +1,213 @@
+// fork.ts — Fork-on-busy engine for orchestrator mode
+//
+// When the orchestrator's main session is busy, new events are handled by
+// forking the main session's transcript and dispatching to the fork in parallel.
+// The on-disk JSONL transcript always reflects the state BEFORE the current
+// dispatch (in-flight messages are memory-only), so the fork inherits all
+// prior history without race conditions.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { CURRENT_SESSION_VERSION, SessionManager } from "@mariozechner/pi-coding-agent";
+
+export type ForkSessionResult = {
+  sessionKey: string;
+  sessionId: string;
+  sessionFile: string;
+};
+
+// ---------------------------------------------------------------------------
+// Session store helpers — read sessions.json directly (SSOT for file paths)
+// ---------------------------------------------------------------------------
+
+type SessionStoreEntry = {
+  sessionId?: string;
+  sessionFile?: string;
+  [key: string]: unknown;
+};
+
+/**
+ * Read sessions.json and find the entry for a given session key.
+ * OpenClaw may store keys in lowercase; we try both.
+ */
+function readStoreEntry(sessionsDir: string, sessionKey: string): SessionStoreEntry | null {
+  const storeFile = path.join(sessionsDir, "sessions.json");
+  try {
+    const store = JSON.parse(fs.readFileSync(storeFile, "utf-8")) as Record<string, SessionStoreEntry>;
+    return store[sessionKey] ?? store[sessionKey.toLowerCase()] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write or update an entry in sessions.json.
+ */
+function writeStoreEntry(sessionsDir: string, sessionKey: string, entry: SessionStoreEntry): boolean {
+  const storeFile = path.join(sessionsDir, "sessions.json");
+  try {
+    let store: Record<string, SessionStoreEntry> = {};
+    try {
+      store = JSON.parse(fs.readFileSync(storeFile, "utf-8"));
+    } catch { /* empty or missing — start fresh */ }
+    store[sessionKey.toLowerCase()] = entry;
+    fs.writeFileSync(storeFile, JSON.stringify(store, null, 2), { encoding: "utf-8" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Delete an entry from sessions.json.
+ */
+function deleteStoreEntry(sessionsDir: string, sessionKey: string): void {
+  const storeFile = path.join(sessionsDir, "sessions.json");
+  try {
+    const store = JSON.parse(fs.readFileSync(storeFile, "utf-8")) as Record<string, unknown>;
+    delete store[sessionKey];
+    delete store[sessionKey.toLowerCase()];
+    fs.writeFileSync(storeFile, JSON.stringify(store, null, 2), { encoding: "utf-8" });
+  } catch {
+    // Best-effort
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Transcript file resolution (via session store)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the transcript file for a session key by reading the session store.
+ * Returns the absolute path, or null if not found.
+ */
+export function resolveTranscriptFile(sessionsDir: string, sessionKey: string): string | null {
+  const entry = readStoreEntry(sessionsDir, sessionKey);
+  if (!entry?.sessionId) return null;
+
+  // Prefer explicit sessionFile field
+  if (entry.sessionFile) {
+    const resolved = path.isAbsolute(entry.sessionFile)
+      ? entry.sessionFile
+      : path.join(sessionsDir, entry.sessionFile);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+
+  // Fallback: conventional {sessionId}.jsonl
+  const conventional = path.join(sessionsDir, `${entry.sessionId}.jsonl`);
+  if (fs.existsSync(conventional)) return conventional;
+
+  // Last resort: scan for files containing the sessionId
+  try {
+    const files = fs.readdirSync(sessionsDir);
+    const match = files.find((f) => f.includes(entry.sessionId!) && f.endsWith(".jsonl"));
+    return match ? path.join(sessionsDir, match) : null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Fork creation
+// ---------------------------------------------------------------------------
+
+/**
+ * Fork the orchestrator session's transcript into a new parallel session.
+ *
+ * The fork inherits all history up to the current dispatch start (on-disk state).
+ * It gets its own session key, write lock, and can dispatch independently.
+ *
+ * Creates a session store entry with lineage metadata (spawnedBy).
+ */
+export function forkOrchestratorSession(opts: {
+  orchestratorSessionKey: string;
+  accountId: string;
+  transcriptFile: string;
+  sessionsDir: string;
+}): ForkSessionResult | null {
+  const { orchestratorSessionKey, accountId, transcriptFile, sessionsDir } = opts;
+
+  if (!fs.existsSync(transcriptFile)) return null;
+
+  try {
+    const manager = SessionManager.open(transcriptFile);
+    const leafId = manager.getLeafId();
+
+    let sessionId: string;
+    let sessionFile: string;
+
+    if (leafId) {
+      // Branch from the current leaf — inherits full transcript history
+      const branched = manager.createBranchedSession(leafId) ?? manager.getSessionFile();
+      const branchedId = manager.getSessionId();
+      if (branched && branchedId) {
+        sessionFile = branched;
+        sessionId = branchedId;
+      } else {
+        return null;
+      }
+    } else {
+      // Fallback: no leaf node — create a header-only fork file manually.
+      sessionId = crypto.randomUUID();
+      const timestamp = new Date().toISOString();
+      const fileTimestamp = timestamp.replace(/[:.]/g, "-");
+      sessionFile = path.join(
+        manager.getSessionDir(),
+        `${fileTimestamp}_${sessionId}.jsonl`,
+      );
+      const header = {
+        type: "session",
+        version: CURRENT_SESSION_VERSION,
+        id: sessionId,
+        timestamp,
+        cwd: manager.getCwd(),
+        parentSession: transcriptFile,
+      };
+      fs.writeFileSync(sessionFile, `${JSON.stringify(header)}\n`, {
+        encoding: "utf-8",
+        mode: 0o600,
+        flag: "wx",
+      });
+    }
+
+    const forkSessionKey = `${orchestratorSessionKey}:fork:${sessionId}`;
+
+    // Register in session store — fail closed if store is unwritable
+    const wrote = writeStoreEntry(sessionsDir, forkSessionKey, {
+      sessionId,
+      sessionFile: path.relative(sessionsDir, sessionFile),
+      updatedAt: Date.now(),
+      spawnedBy: orchestratorSessionKey,
+      parentSessionKey: orchestratorSessionKey,
+      forkedFromParent: true,
+    });
+    if (!wrote) return null;
+
+    return { sessionKey: forkSessionKey, sessionId, sessionFile };
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Fork cleanup (store-driven)
+// ---------------------------------------------------------------------------
+
+/**
+ * Clean up a fork session: delete transcript file AND session store entry.
+ */
+export function cleanupForkSession(opts: {
+  sessionFile: string;
+  sessionKey: string;
+  sessionsDir: string;
+}): void {
+  try {
+    if (fs.existsSync(opts.sessionFile)) {
+      fs.unlinkSync(opts.sessionFile);
+    }
+  } catch {
+    // Best-effort file cleanup
+  }
+  deleteStoreEntry(opts.sessionsDir, opts.sessionKey);
+}