@parall/parall 1.33.0 → 1.35.0

package/dist/gateway.d.ts

@@ -1,7 +1,16 @@
+import type { PluginRuntime } from 'openclaw/plugin-sdk';
 import type { ChannelPlugin } from 'openclaw/plugin-sdk/core';
 /** Extract ChannelGatewayAdapter from ChannelPlugin (removed from public SDK exports in 2026.3.24). */
 type ChannelGatewayAdapter<T = unknown> = NonNullable<ChannelPlugin<T>['gateway']>;
+import { type DispatchAdapter } from '@parall/agent-core';
 import type { ResolvedParallAccount } from './types.js';
+export declare function createOpenClawDispatchAdapter(opts: {
+    core: PluginRuntime;
+    cfg: Record<string, unknown>;
+    accountId: string;
+    sessionsDir: string;
+    workspaceDir: string;
+}): DispatchAdapter;
 export declare const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount>;
 export {};
 //# sourceMappingURL=gateway.d.ts.map

package/dist/gateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,uGAAuG;AACvG,KAAK,qBAAqB,CAAC,CAAC,GAAG,OAAO,IAAI,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AAgCnF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA8SxD,eAAO,MAAM,aAAa,EAAE,qBAAqB,CAAC,qBAAqB,CAmJtE,CAAC"}
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,uGAAuG;AACvG,KAAK,qBAAqB,CAAC,CAAC,GAAG,OAAO,IAAI,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AACnF,OAAO,EAOL,KAAK,eAAe,EAGrB,MAAM,oBAAoB,CAAC;AAqB5B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAiKxD,wBAAgB,6BAA6B,CAAC,IAAI,EAAE;IAClD,IAAI,EAAE,aAAa,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,eAAe,CA0KlB;AAED,eAAO,MAAM,aAAa,EAAE,qBAAqB,CAAC,qBAAqB,CAmJtE,CAAC"}

package/dist/gateway.js

@@ -145,8 +145,41 @@ async function waitForOpenClawSessionId(sessionsDir, sessionKey, timeoutMs = 10_
     }
     return null;
 }
-function createOpenClawDispatchAdapter(opts) {
+export function createOpenClawDispatchAdapter(opts) {
     const activeStreams = new Map();
+    let configFallbackWarned = false;
+    /**
+     * Resolve the config for one dispatch. OpenClaw hot-reloads
+     * `agents.defaults.model` / `models.providers` WITHOUT restarting channel
+     * plugins, so the `ctx.cfg` snapshot captured at startAccount goes stale the
+     * moment the operator switches the agent's model — every run would keep the
+     * old model until the whole gateway restarts. `core.config.current()` is the
+     * host's live (hot-reload-refreshed) config; fall back to the startup
+     * snapshot on hosts that predate the API. The fallback warns once per
+     * degradation streak (latch resets on success) — silently dispatching with
+     * the stale snapshot would recreate the invisible model-switch mismatch this
+     * function exists to fix.
+     */
+    function resolveDispatchConfig(log) {
+        try {
+            const current = opts.core.config?.current?.();
+            if (current && typeof current === 'object') {
+                configFallbackWarned = false;
+                return current;
+            }
+            if (!configFallbackWarned) {
+                configFallbackWarned = true;
+                log?.warn?.(`parall[${opts.accountId}]: config.current() unavailable on this host — dispatching with the startup config snapshot; model switches need a gateway restart until then`);
+            }
+        }
+        catch (err) {
+            if (!configFallbackWarned) {
+                configFallbackWarned = true;
+                log?.warn?.(`parall[${opts.accountId}]: config.current() failed (${String(err)}) — dispatching with the startup config snapshot; model switches need a gateway restart until then`);
+            }
+        }
+        return opts.cfg;
+    }
     return {
         abortDispatch(sessionKey) {
             activeStreams.get(sessionKey)?.fail(new Error('dispatch deadline exceeded'));
@@ -172,7 +205,7 @@ function createOpenClawDispatchAdapter(opts) {
                 let turnGroupKey = '';
                 const run = opts.core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
                     ctx: buildInboundCtx(opts.core, opts.accountId, event, sessionKey, promptBody, earlierEvents),
-                    cfg: opts.cfg,
+                    cfg: resolveDispatchConfig(context.log),
                     dispatcherOptions: {
                         deliver: async (payload) => {
                             const replyText = payload.text?.trim();

package/dist/index.bundle.mjs

@@ -27010,6 +27010,7 @@ var ENDPOINTS = {
   // Org-scoped
   ORG: (orgId) => `${API_BASE}/orgs/${orgId}`,
   ORG_MEMBERS: (orgId) => `${API_BASE}/orgs/${orgId}/members`,
+  TEAMS: (orgId) => `${API_BASE}/orgs/${orgId}/teams`,
   ORG_MEMBERS_ONLINE: (orgId) => `${API_BASE}/orgs/${orgId}/members/online`,
   ORG_MEMBER: (orgId, userId) => `${API_BASE}/orgs/${orgId}/members/${userId}`,
   ORG_MEMBER_CHATS: (orgId, memberId) => `${API_BASE}/orgs/${orgId}/members/${memberId}/chats`,
@@ -27054,6 +27055,7 @@ var ENDPOINTS = {
   AGENT: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}`,
   AGENT_API_KEYS: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/api-keys`,
   AGENT_API_KEY: (orgId, agentId, key) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/api-keys/${key}`,
+  AGENT_API_KEY_REGENERATE: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/api-keys/regenerate`,
   AGENT_AVATAR: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/avatar`,
   AGENT_ACTIVITY: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/activity`,
   AGENT_MONITOR: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/monitor`,
@@ -27093,6 +27095,7 @@ var ENDPOINTS = {
   MACHINE_AGENT_WORKSPACE_SETUP: (orgId, machineId, agentId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/agents/${agentId}/workspace/setup`,
   MACHINE_LLM_SOURCE: (orgId, machineId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/llm-source`,
   MACHINE_PROVIDER_ENABLED: (orgId, machineId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/provider-enabled`,
+  MACHINE_CAPABILITIES: (orgId, machineId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/capabilities`,
   MACHINE_RUNTIME_AUTH: (orgId, machineId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/runtime-auth`,
   MACHINE_KEYS: (orgId, machineId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/keys`,
   MACHINE_KEY: (orgId, machineId, keyId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/keys/${keyId}`,
@@ -27113,6 +27116,12 @@ var ENDPOINTS = {
   MACHINES_ME_AGENT_WORKSPACE_STATE: (agentId) => `${API_BASE}/machines/me/agents/${agentId}/workspace-state`,
   MACHINES_ME_WS_TICKET: `${API_BASE}/machines/me/ws/ticket`,
   MACHINES_ME_BROWSE_RESPONSE: (requestId) => `${API_BASE}/machines/me/browse-response/${requestId}`,
+  // Hosted browser live-viewer control plane (api-server, NOT clip-service):
+  // the web client drives WebRTC signaling + tab nav through VIEWER_COMMAND;
+  // api-server brokers each command to the host daemon via the machine:{id}
+  // request/reply bridge (mirrors filesystem browse), and the daemon replies on
+  // VIEWER_RESPONSE. See docs/engineering-design/hosted-browser-provider-design.md.
+  MACHINES_ME_BROWSER_PROFILE_VIEWER_RESPONSE: (requestId) => `${API_BASE}/machines/me/browser-profiles/viewer-response/${requestId}`,
   // Tasks (org-scoped)
   TASKS: (orgId) => `${API_BASE}/orgs/${orgId}/tasks`,
   TASK: (orgId, taskId) => `${API_BASE}/orgs/${orgId}/tasks/${taskId}`,
@@ -27178,6 +27187,9 @@ var ENDPOINTS = {
   // Wiki Path Scopes (AFCS ACL)
   WIKI_PATH_SCOPES: (orgId, wikiId) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/path-scopes`,
   WIKI_PATH_SCOPE: (orgId, wikiId, scopeId) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/path-scopes/${scopeId}`,
+  // Wiki Path Restrictions (AFCS narrowing ACL — private subtrees)
+  WIKI_RESTRICTIONS: (orgId, wikiId) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/restrictions`,
+  WIKI_RESTRICTION: (orgId, wikiId, restrictionId) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/restrictions/${restrictionId}`,
   WIKI_ACCESS_STATUS: (orgId, wikiId) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/access-status`,
   WIKI_ACCESS_REQUESTS: (orgId, wikiId) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/access-requests`,
   // Wiki History (commits, file commits, blame)
@@ -27226,6 +27238,8 @@ var ENDPOINTS = {
   PUSH_VAPID_KEY: `${API_BASE}/push/vapid-key`,
   // Notification preferences
   NOTIFICATION_PREFERENCES: `${API_BASE}/notification-preferences`,
+  // Unified search (messages + tasks + wiki, org-scoped)
+  SEARCH: (orgId) => `${API_BASE}/orgs/${orgId}/search`,
   // Feature flags (org-scoped, server-evaluated)
   FEATURE_FLAGS: (orgId) => `${API_BASE}/orgs/${orgId}/feature-flags`,
   // Billing & Credits (org-scoped)
@@ -27241,6 +27255,7 @@ var ENDPOINTS = {
   // Clips (org-scoped, served by clip-service)
   CLIPS: (orgId) => `${CLIP_BASE}/orgs/${orgId}/clips`,
   CLIP: (orgId, clipId) => `${CLIP_BASE}/orgs/${orgId}/clips/${clipId}`,
+  CLIPS_BULK_METADATA: (orgId) => `${CLIP_BASE}/orgs/${orgId}/clips/bulk-metadata`,
   CLIP_AGENTS: (orgId, clipId) => `${CLIP_BASE}/orgs/${orgId}/clips/${clipId}/agents`,
   AGENT_CLIPS: (orgId, agentId) => `${CLIP_BASE}/orgs/${orgId}/agents/${agentId}/clips`,
   AGENT_CLIP: (orgId, agentId, clipId) => `${CLIP_BASE}/orgs/${orgId}/agents/${agentId}/clips/${clipId}`,
@@ -27253,6 +27268,9 @@ var ENDPOINTS = {
   BROWSER_PROFILE_RESET: (orgId, profileId) => `${CLIP_BASE}/orgs/${orgId}/browser-profiles/${profileId}/reset`,
   BROWSER_PROFILE_CONSENTS: (orgId, profileId) => `${CLIP_BASE}/orgs/${orgId}/browser-profiles/${profileId}/consents`,
   BROWSER_PROFILE_CONSENT: (orgId, profileId, clipId) => `${CLIP_BASE}/orgs/${orgId}/browser-profiles/${profileId}/consents/${clipId}`,
+  // Live viewer command — on api-server (API_BASE), not clip-service: it rides
+  // the machine control-plane request/reply bridge that lives in api-server.
+  BROWSER_PROFILE_VIEWER_COMMAND: (orgId, profileId) => `${API_BASE}/orgs/${orgId}/browser-profiles/${profileId}/viewer/command`,
   // Clip registry (global, served by clip-service → Pinix Hub proxy)
   CLIP_REGISTRY: () => `${CLIP_BASE}/registry/clips`
 };
@@ -27329,6 +27347,7 @@ var WS_EVENTS = {
   MACHINE_CONFIG_UPDATED: "machine.config.updated",
   MACHINE_CLIP_SYNC: "machine.clip.sync",
   MACHINE_BROWSER_PROFILE_LIFECYCLE: "machine.browser_profile.lifecycle",
+  MACHINE_BROWSER_PROFILE_VIEWER: "machine.browser_profile.viewer",
   AGENT_NEW_SESSION: "agent.new_session",
   CLIP_CREATED: "clip.created",
   CLIP_REMOVED: "clip.removed",
@@ -27359,8 +27378,13 @@ var ParallClient = class _ParallClient {
   /** Proactive refresh when token expires within this window (seconds). */
   static REFRESH_THRESHOLD_S = 5 * 60;
   static normalizeFetchError(err) {
-    if (typeof DOMException !== "undefined" && err instanceof DOMException && (err.name === "TimeoutError" || err.name === "AbortError")) {
-      return new ApiError(0, "Request timed out", "REQUEST_TIMEOUT");
+    if (typeof DOMException !== "undefined" && err instanceof DOMException) {
+      if (err.name === "TimeoutError") {
+        return new ApiError(0, "Request timed out", "REQUEST_TIMEOUT");
+      }
+      if (err.name === "AbortError") {
+        return new ApiError(0, "Request aborted", "REQUEST_ABORTED");
+      }
     }
     const apiError = new ApiError(0, "Network request failed", "NETWORK_ERROR");
     if (err instanceof Error && err.message && err.message !== "Failed to fetch") {
@@ -27467,13 +27491,18 @@ var ParallClient = class _ParallClient {
         url += `?${qs}`;
     }
     const headers = this.buildHeaders();
+    const timeoutSignal = AbortSignal.timeout(opts?.timeoutMs ?? 15e3);
+    const signal = opts?.signal ? AbortSignal.any([opts.signal, timeoutSignal]) : timeoutSignal;
     let res;
     try {
       res = await fetch(url, {
         method,
         headers,
         body: body ? JSON.stringify(body) : void 0,
-        signal: AbortSignal.timeout(opts?.timeoutMs ?? 15e3)
+        signal,
+        // keepalive lets a request fired during page unload (e.g. the browser
+        // viewer's stream.close on pagehide) outlive the document.
+        keepalive: opts?.keepalive
       });
     } catch (err) {
       throw _ParallClient.normalizeFetchError(err);
@@ -27644,6 +27673,10 @@ var ParallClient = class _ParallClient {
     const res = await this.request("GET", ENDPOINTS.ORG_MEMBERS(orgId));
     return res.data;
   }
+  async getTeams(orgId) {
+    const res = await this.request("GET", ENDPOINTS.TEAMS(orgId));
+    return res.data;
+  }
   async getOnlineMembers(orgId) {
     const res = await this.request("GET", ENDPOINTS.ORG_MEMBERS_ONLINE(orgId));
     return res.user_ids ?? [];
@@ -27882,6 +27915,10 @@ var ParallClient = class _ParallClient {
   async createAgentApiKey(orgId, agentId) {
     return this.request("POST", ENDPOINTS.AGENT_API_KEYS(orgId, agentId));
   }
+  /** Revokes all of the agent's active API keys and mints a replacement. */
+  async regenerateAgentApiKey(orgId, agentId) {
+    return this.request("POST", ENDPOINTS.AGENT_API_KEY_REGENERATE(orgId, agentId));
+  }
   async revokeAgentApiKey(orgId, agentId, key) {
     return this.request("DELETE", ENDPOINTS.AGENT_API_KEY(orgId, agentId, key));
   }
@@ -28053,6 +28090,17 @@ var ParallClient = class _ParallClient {
       provider_enabled: providerEnabled
     });
   }
+  /**
+   * Replace the machine's capability set (admin). Primary use: healing a
+   * machine that registered without `browser_provider` during the capability
+   * migration's rolling-deploy window. Removing `agent_host` is rejected by the
+   * server while agents are attached (409 AGENTS_STILL_ATTACHED).
+   */
+  async patchMachineCapabilities(orgId, machineId, capabilities) {
+    return this.request("PATCH", ENDPOINTS.MACHINE_CAPABILITIES(orgId, machineId), {
+      capabilities
+    });
+  }
   /** Get machine-level runtime auth state. */
   async getMachineRuntimeAuth(orgId, machineId) {
     return this.request("GET", ENDPOINTS.MACHINE_RUNTIME_AUTH(orgId, machineId));
@@ -28143,6 +28191,22 @@ var ParallClient = class _ParallClient {
   async postBrowseResponse(requestId, response) {
     return this.request("POST", ENDPOINTS.MACHINES_ME_BROWSE_RESPONSE(requestId), response);
   }
+  /**
+   * `POST /machines/me/browser-profiles/viewer-response/{requestId}` — daemon
+   * reply to a `machine.browser_profile.viewer` control command. Wakes the
+   * api-server request/reply bridge (mirrors {@link postBrowseResponse}).
+   */
+  async postBrowserProfileViewerResponse(requestId, response) {
+    return this.request("POST", ENDPOINTS.MACHINES_ME_BROWSER_PROFILE_VIEWER_RESPONSE(requestId), response);
+  }
+  /**
+   * `POST /orgs/{orgId}/browser-profiles/{profileId}/viewer/command` — drive the
+   * hosted browser live viewer (WebRTC signaling + tab nav). Authz: profile
+   * owner or org admin. api-server brokers the command to the host daemon.
+   */
+  async browserViewerCommand(orgId, profileId, req, opts) {
+    return this.request("POST", ENDPOINTS.BROWSER_PROFILE_VIEWER_COMMAND(orgId, profileId), req, void 0, false, opts);
+  }
   async resizeMachine(orgId, machineId, spec) {
     return this.request("PATCH", ENDPOINTS.MACHINE_SPEC(orgId, machineId), spec);
   }
@@ -28421,6 +28485,9 @@ var ParallClient = class _ParallClient {
   async getWikiNodeSections(orgId, wikiId, params) {
     return this.request("GET", ENDPOINTS.WIKI_NODE_SECTIONS(orgId, wikiId), void 0, params);
   }
+  async search(orgId, params, opts) {
+    return this.request("GET", ENDPOINTS.SEARCH(orgId), void 0, params, false, opts);
+  }
   async searchWiki(orgId, wikiId, params) {
     return this.request("GET", ENDPOINTS.WIKI_SEARCH(orgId, wikiId), void 0, params);
   }
@@ -28516,6 +28583,17 @@ var ParallClient = class _ParallClient {
   async deleteWikiPathScope(orgId, wikiId, scopeId) {
     await this.request("DELETE", ENDPOINTS.WIKI_PATH_SCOPE(orgId, wikiId, scopeId));
   }
+  // ---- Wiki Path Restrictions (narrowing ACL — private subtrees) ----
+  async getWikiRestrictions(orgId, wikiId) {
+    const res = await this.request("GET", ENDPOINTS.WIKI_RESTRICTIONS(orgId, wikiId));
+    return res.data;
+  }
+  async createWikiRestriction(orgId, wikiId, data) {
+    return this.request("POST", ENDPOINTS.WIKI_RESTRICTIONS(orgId, wikiId), data);
+  }
+  async deleteWikiRestriction(orgId, wikiId, restrictionId) {
+    await this.request("DELETE", ENDPOINTS.WIKI_RESTRICTION(orgId, wikiId, restrictionId));
+  }
   async getWikiAccessStatus(orgId, wikiId, path7) {
     return this.request("GET", ENDPOINTS.WIKI_ACCESS_STATUS(orgId, wikiId), void 0, path7 ? { path: path7 } : void 0);
   }
@@ -28678,6 +28756,10 @@ var ParallClient = class _ParallClient {
   async updateClip(orgId, clipId, req) {
     return this.request("PATCH", ENDPOINTS.CLIP(orgId, clipId), req);
   }
+  /** Atomically set display_name and/or description on multiple clip instances (application metadata). */
+  async bulkUpdateClipMetadata(orgId, req) {
+    return this.request("POST", ENDPOINTS.CLIPS_BULK_METADATA(orgId), req);
+  }
   async deleteClip(orgId, clipId) {
     await this.request("DELETE", ENDPOINTS.CLIP(orgId, clipId));
   }
@@ -30209,7 +30291,7 @@ var ParallAgentGateway = class {
             this.dispatchState.mainDispatching = true;
             void this.drainMainBuffer();
           }
-        }, 5e3);
+        }, 5e3).unref();
       }
     }
   }
@@ -32407,6 +32489,26 @@ async function waitForOpenClawSessionId(sessionsDir, sessionKey, timeoutMs = 1e4
 }
 function createOpenClawDispatchAdapter(opts) {
   const activeStreams = /* @__PURE__ */ new Map();
+  let configFallbackWarned = false;
+  function resolveDispatchConfig(log) {
+    try {
+      const current = opts.core.config?.current?.();
+      if (current && typeof current === "object") {
+        configFallbackWarned = false;
+        return current;
+      }
+      if (!configFallbackWarned) {
+        configFallbackWarned = true;
+        log?.warn?.(`parall[${opts.accountId}]: config.current() unavailable on this host \u2014 dispatching with the startup config snapshot; model switches need a gateway restart until then`);
+      }
+    } catch (err) {
+      if (!configFallbackWarned) {
+        configFallbackWarned = true;
+        log?.warn?.(`parall[${opts.accountId}]: config.current() failed (${String(err)}) \u2014 dispatching with the startup config snapshot; model switches need a gateway restart until then`);
+      }
+    }
+    return opts.cfg;
+  }
   return {
     abortDispatch(sessionKey) {
       activeStreams.get(sessionKey)?.fail(new Error("dispatch deadline exceeded"));
@@ -32432,7 +32534,7 @@ function createOpenClawDispatchAdapter(opts) {
         let turnGroupKey = "";
         const run = opts.core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
           ctx: buildInboundCtx(opts.core, opts.accountId, event, sessionKey, promptBody, earlierEvents),
-          cfg: opts.cfg,
+          cfg: resolveDispatchConfig(context2.log),
           dispatcherOptions: {
             deliver: async (payload) => {
               const replyText = payload.text?.trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/parall",
-  "version": "1.33.0",
+  "version": "1.35.0",
   "description": "OpenClaw channel plugin for Parall IM",
   "license": "MIT",
   "repository": {
@@ -16,8 +16,8 @@
     "openclaw.plugin.json"
   ],
   "dependencies": {
-    "@parall/agent-core": "1.33.0",
-    "@parall/sdk": "1.33.0"
+    "@parall/agent-core": "1.35.0",
+    "@parall/sdk": "1.35.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/skills/parall-wiki/SKILL.md

@@ -7,129 +7,128 @@ description: "Parall wiki operations: read, search, edit, and propose changes to
 
 Manage organization wikis via the Parall CLI. Auth is pre-configured.
 
-## Browsing (no local state needed)
+## Mental model
+
+Wiki editing works on a **local workspace**: `parall wiki sync` downloads the
+wiki into a directory on disk, you edit those files with your normal file
+tools, then `parall wiki changeset create` uploads the result as a proposal.
+There is no git in the workspace — your edits are detected by diffing against
+the synced baseline.
+
+Key facts the commands won't tell you:
+
+- **Workspace location is fixed.** Sync output and `parall wiki status` print
+  the absolute workspace path (`synced → /path/to/<slug>` / `Mount: ...`).
+  Always address wiki files by that absolute path — your shell cwd is usually
+  NOT inside the workspace.
+- **Text files only.** Changesets reject binary content. Don't put images or
+  archives in the workspace; binary uploads go through the web UI.
+- **`cat`, `search`, `query`, `outline`, and `section` read your local
+  workspace copy when it exists** — including your own unproposed edits. Add
+  `--remote` to `cat` to read the server version instead.
+- **`search`/`query` are keyword (lexical) matching**, not semantic search.
+  `query` additionally ranks whole documents — better for multi-word
+  questions; `search` for a single identifier.
+- The `<wiki>` argument is the slug or ID from `parall wiki list`; with a
+  single wiki in the org it can be omitted.
+
+## Core workflow
 
 ```bash
-parall wiki list                       # List all wikis
-parall wiki tree <slug>                 # List files and directories
-parall wiki tree <slug> --path docs/    # List a subdirectory
+parall wiki sync                                  # 1. get/update files (prints workspace path)
+# 2. read + edit files under the workspace path with standard file tools
+parall wiki diff <wiki>                            # 3. review exactly what you'll propose
+parall wiki changeset create <wiki> --title "..."  # 4. submit
 ```
 
-## Editing
+Always sync before starting and always check `diff` before proposing — the
+changeset uploads the full content of every changed file.
 
-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.
+Unprotected paths auto-merge immediately (`auto_merged: true`); protected
+paths stay open for human review. Follow the returned `next_action` either way.
 
-### Step 1: Sync
+## Stale base (server moved since your sync)
 
-```bash
-parall wiki sync <slug>
-```
-
-This downloads wiki files to a local directory. The output includes the
-**absolute mount path** for each wiki (e.g. `synced → /path/to/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:
+If files changed on the server after your last sync, `changeset create` is
+rejected — both by a CLI precheck and by the server (409 `STALE_BASE`) — so
+you can't silently overwrite someone's concurrent edit. Recovery:
 
 ```bash
-parall wiki status <slug>
+parall wiki sync          # pull latest; your local edits are preserved
+# if a file conflicts, resolve it (see next section)
+parall wiki changeset create <wiki> --title "..."
 ```
 
-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`.
+## Sync conflicts
 
-### Step 3: Edit files
+`sync` three-way merges. When both you and the server changed the same file,
+your file is left intact and the upstream copy lands under
+`<workspace>/.parall-wiki/conflicts/`:
 
-Use standard file tools (`read`, `write`, `edit`) on files under the mount path.
+| Marker | Meaning |
+|--------|---------|
+| `conflicts/<path>.remote` | Server has different content for `<path>` |
+| `conflicts/<path>.remote-deleted` | Server deleted `<path>`; you still have edits |
 
-### Step 4: Review changes
+All paths below are relative to the workspace root. Pick one:
 
 ```bash
-parall wiki diff <slug>       # Shows unified diff of all local changes
-parall wiki status <slug>     # Shows which files changed with +/- line counts
-```
+# Accept upstream (drop your edit):
+cp <workspace>/.parall-wiki/conflicts/<path>.remote <workspace>/<path>
 
-Always review before proposing.
+# Keep yours / hand-merge: edit <workspace>/<path> to final content, then
+parall wiki changeset create <wiki> --title "Reconcile <path>"
 
-### Step 5: Propose changeset
-
-```bash
-parall wiki changeset create <slug> --title "Description of changes"
+# Accept server delete (.remote-deleted only):
+rm <workspace>/<path>
 ```
 
-This uploads your local changes. Unprotected paths auto-merge immediately; the
-CLI prints `auto_merged: true` and refreshes the local manifest. Protected
-paths remain as a changeset for review; follow the returned `next_action`.
-
-## Changeset Management
-
-```bash
-parall wiki changeset list <slug>               # List all changesets
-parall wiki changeset show <changesetId> <slug> # Show detail + feedback
-parall wiki changeset diff <changesetId> <slug> # Show changeset diff
-```
+Then re-run `parall wiki sync` and delete the used marker file. Conflicts
+exit 0 (they need your decision); `failed[]` entries (download error,
+shape-conflict) exit 1 and retry on the next sync.
 
-If a changeset is rejected, fix the files locally and re-propose:
+## Changesets
 
 ```bash
-parall wiki changeset create <slug> --update <changesetId>
+parall wiki changeset list <wiki>
+parall wiki changeset show <changesetId> <wiki>     # status + feedback
+parall wiki changeset diff <changesetId> <wiki>
+parall wiki changeset create <wiki> --update <id>   # re-propose after rejection (title inherited)
 ```
 
-The title is inherited from the original changeset — no need to repeat it.
-
-## Handling sync conflicts
-
-`wiki sync` runs a three-way merge. When both you and the server changed the
-same file, sync **does not overwrite your work**. It leaves your file intact
-and drops the upstream version under `.parall-wiki/conflicts/`:
-
-| Marker | Meaning |
-|--------|---------|
-| `.parall-wiki/conflicts/<path>.remote` | Server has different content (concurrent edit, new file collision, or server changed a file you deleted) |
-| `.parall-wiki/conflicts/<path>.remote-deleted` | Server deleted the file; you still have edits |
-
-stderr prints one line per conflict. Recovery:
+Rejected: read the feedback (`show` / `status`), fix the files, re-propose
+with `--update <id>`. Conflict status: `sync`, resolve, then `--update <id>`.
 
-**Accept upstream** (drop your edit):
-```bash
-cp .parall-wiki/conflicts/<path>.remote <path>
-parall wiki sync
-```
+Re-propose REPLACES the changeset's previous contents with your current
+workspace diff — to withdraw a file from the proposal, revert it locally
+(restore the synced content) and re-propose; it drops out of the changeset.
 
-**Keep yours** (or hand-merge, then propose):
-```bash
-# edit <path> to final content
-parall wiki diff <slug>
-parall wiki changeset create <slug> --title "Reconcile <path>"
-parall wiki sync   # fast-forwards after server merges
-```
+## Discovery & history
 
-**Accept server delete** (`.remote-deleted` only):
 ```bash
-rm <path>
-parall wiki sync
+parall wiki query "how is auth configured" <wiki>   # multi-word lookup (query FIRST, wiki second)
+parall wiki search "JWT" <wiki>                     # single keyword (query FIRST, wiki second)
+parall wiki outline <wiki> --path docs/             # heading structure
+parall wiki cat docs/auth.md <wiki>                 # print a file (--remote for server version)
+parall wiki tree <wiki>                             # list files
+parall wiki log <wiki>                              # recent operations
+parall wiki log <wiki> docs/auth.md                 # per-file commit history
 ```
 
-Sync failures (`download`, `shape-conflict`) set exit code 1 and retry on
-next sync. Conflicts exit 0 — they need your decision, not a retry.
+## Permissions
 
-## Discarding local changes
-
-```bash
-parall wiki reset <slug>      # Restore all files to last synced state
-```
+Reads and writes are ACL-checked server-side per path. `parall wiki access
+<path>` shows your level for a path. On a `PERMISSION_DENIED`, errors include
+a `Request approval:` hint — use `parall wiki request-access <path> --reason
+"..."` to file an approval card for a maintainer, then re-sync after approval.
 
-## History
+## Recovery
 
 ```bash
-parall wiki log <slug>        # Recent wiki operations
+parall wiki reset <wiki>    # discard ALL local edits, restore last-synced state
+parall wiki status <wiki>   # local changes + your changesets, anytime
 ```
 
-CLI success output is JSON; errors may add a plain-text `Request approval:` line on a `PERMISSION_DENIED` — read both. Run `parall wiki --help` for full options.
+CLI success output is JSON on stdout (human summary on stderr); errors state
+the reason and the next step — follow them. `parall wiki --help` for the
+full command list.

package/src/gateway.ts

@@ -195,7 +195,7 @@ async function waitForOpenClawSessionId(
   return null;
 }
 
-function createOpenClawDispatchAdapter(opts: {
+export function createOpenClawDispatchAdapter(opts: {
   core: PluginRuntime;
   cfg: Record<string, unknown>;
   accountId: string;
@@ -203,6 +203,43 @@ function createOpenClawDispatchAdapter(opts: {
   workspaceDir: string;
 }): DispatchAdapter {
   const activeStreams = new Map<string, ReturnType<typeof createRuntimeEventStream>>();
+  let configFallbackWarned = false;
+
+  /**
+   * Resolve the config for one dispatch. OpenClaw hot-reloads
+   * `agents.defaults.model` / `models.providers` WITHOUT restarting channel
+   * plugins, so the `ctx.cfg` snapshot captured at startAccount goes stale the
+   * moment the operator switches the agent's model — every run would keep the
+   * old model until the whole gateway restarts. `core.config.current()` is the
+   * host's live (hot-reload-refreshed) config; fall back to the startup
+   * snapshot on hosts that predate the API. The fallback warns once per
+   * degradation streak (latch resets on success) — silently dispatching with
+   * the stale snapshot would recreate the invisible model-switch mismatch this
+   * function exists to fix.
+   */
+  function resolveDispatchConfig(log?: { warn?: (msg: string) => void }): Record<string, unknown> {
+    try {
+      const current = opts.core.config?.current?.();
+      if (current && typeof current === 'object') {
+        configFallbackWarned = false;
+        return current as unknown as Record<string, unknown>;
+      }
+      if (!configFallbackWarned) {
+        configFallbackWarned = true;
+        log?.warn?.(
+          `parall[${opts.accountId}]: config.current() unavailable on this host — dispatching with the startup config snapshot; model switches need a gateway restart until then`,
+        );
+      }
+    } catch (err) {
+      if (!configFallbackWarned) {
+        configFallbackWarned = true;
+        log?.warn?.(
+          `parall[${opts.accountId}]: config.current() failed (${String(err)}) — dispatching with the startup config snapshot; model switches need a gateway restart until then`,
+        );
+      }
+    }
+    return opts.cfg;
+  }
 
   return {
     abortDispatch(sessionKey: string): void {
@@ -238,7 +275,7 @@ function createOpenClawDispatchAdapter(opts: {
             promptBody,
             earlierEvents,
           ),
-          cfg: opts.cfg,
+          cfg: resolveDispatchConfig(context.log),
           dispatcherOptions: {
             deliver: async (payload: { text?: string }) => {
               const replyText = payload.text?.trim();