@parall/parall 1.42.1 → 1.43.0

package/package.json

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

package/skills/parall-platform/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: parall-platform
-description: "Parall platform queries and lightweight agent provisioning: list org members, agents, chats, read message history, check identity, or create another agent. Use when: user asks about org members, who's online, chat history, agent list, creating an agent, or identity/auth questions."
+description: "Parall platform queries and lightweight agent provisioning: list org members, agents, chats, read message history, check identity, create another agent, or walk the prll:// reference graph (resolve URIs, backlinks, multi-hop graph). Use when: user asks about org members, who's online, chat history, agent list, creating an agent, identity/auth questions, or you need to find what an entity is connected to / who references it."
 ---
 
 # Parall Platform
@@ -81,11 +81,11 @@ settled questions or repeat known mistakes. This searches live org data
 can see.
 
 ```bash
-# Semantic + keyword search across messages, tasks, and wiki
+# Semantic + keyword search across messages, tasks, wiki, and comments
 parall search "auth v5 upgrade"
 
-# Restrict entity types (m=message, t=task, w=wiki). --channel narrows the
-# MESSAGE hits to one chat (tasks/wiki are unaffected by it).
+# Restrict entity types (m=message, t=task, w=wiki, c=comment). --channel
+# narrows the MESSAGE hits to one chat (tasks/wiki/comments are unaffected).
 parall search "auth v5 upgrade" --types m,w --channel prll://cht_eng
 
 # Time-box to recent activity (RFC3339 or YYYY-MM-DD). Narrows messages + tasks;
@@ -206,6 +206,8 @@ Every entity is addressable with a `prll://` URI. Common prefixes you'll see in
 | `prll://usr_` | User (human or agent) | parall-platform |
 | `prll://cht_` | Chat | parall-platform |
 | `prll://msg_` | Message | parall-platform |
+| `prll://cmt_` | Comment (on tasks, wiki pages, changesets) | by target: task comment → parall-tasks, wiki/changeset comment → parall-wiki |
+| `prll://ase_` | Agent session | parall-platform |
 | `prll://tsk_` | Task | parall-tasks |
 | `prll://prj_` | Project | parall-tasks |
 | `prll://sch_` | Schedule (time trigger) | parall-schedules |
@@ -241,6 +243,23 @@ parall refs graph prll://tsk_xxx --depth 2
 
 `refs graph` traverses both directions (inbound + outbound) and returns `nodes`
 and `edges` with each node's hop `depth`. `truncated: true` means a size cap clipped
-the result — narrow it with a smaller `--depth`.
+the result — narrow it with a smaller `--depth`. Edges carry `context` — the
+author's annotation from `[context](prll://...)` — telling you *why* two
+entities are linked, not just that they are.
+
+The graph returns bare node URIs (no titles). The usual two-step: `refs graph`
+for topology, then batch-`refs resolve` the node URIs you care about for
+titles/status. If graph rejects your URI with a path/anchor error, strip it to
+the entity root (`prll://wik_xxx/docs/a.md` → `prll://wik_xxx`) and re-query —
+but note this WIDENS the query to the whole entity, not that one file: the
+graph seeds from the wiki id, so a specific file's outbound links may sit
+deeper in the result (or past the size caps). For refs pointing AT one file
+(inbound), `refs backlinks` on the full file URI is precise. There is no
+precise query for one file's OUTBOUND edges today — the widened root graph is
+best-effort for those, or read the file itself for its `prll://` links.
+Wiki-file nodes inside a graph *result* do legitimately carry paths.
+
+`refs backlinks` items include a `snippet` of the referencing content — often
+enough to judge relevance without fetching the source entity.
 
 CLI success output is JSON. Errors print a JSON line (`{"error","status","code",...}`) and, on a `PERMISSION_DENIED`, may add a plain-text `Request approval:` line — read both.

package/src/config-manager.ts

@@ -1,3 +1,8 @@
+import {
+  type AgentCapability,
+  extractCapabilities,
+  materializeChannelCapabilities,
+} from '@parall/agent-core';
 import type { ParallClient } from '@parall/sdk';
 import type { PlatformConfigResponse } from '@parall/sdk';
 import * as fs from 'node:fs';
@@ -9,6 +14,36 @@ interface CachedPlatformConfig {
   fetchedAt: string;
 }
 
+// Channel-capability snapshot for the OTHER consumers of capability state:
+// the before_prompt_build hook (fragments into the system prompt — evaluated
+// every prompt build, so a refresh reaches the very next turn without any
+// restart) and the gateway's getCapabilityKeys (hint routing). Updated by
+// applyChannelCapabilitySnapshot alongside every config apply, so the shim
+// materialization and the declaration can never diverge within a refresh.
+// Process-global BY THE SAME assumption as runtime.ts's agentIdentity:
+// hosted agents run one-agent-per-pod, so a single snapshot is correct. A
+// future multi-account host would need this keyed per account together with
+// that identity global — do not fix one without the other.
+let currentCapabilities: AgentCapability[] = [];
+
+export function getChannelCapabilityFragments(): string[] {
+  return currentCapabilities.map((c) => c.fragment);
+}
+
+export function getChannelCapabilityKeys(): string[] {
+  return currentCapabilities.map((c) => c.key);
+}
+
+function applyChannelCapabilitySnapshot(
+  stateDir: string,
+  config: Record<string, unknown>,
+  log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void },
+): void {
+  const caps = extractCapabilities(config);
+  materializeChannelCapabilities(stateDir, caps, log);
+  currentCapabilities = caps;
+}
+
 interface ConfigManagerOpts {
   client: ParallClient;
   stateDir: string;
@@ -204,6 +239,7 @@ export async function fetchAndApplyPlatformConfig(opts: ConfigManagerOpts): Prom
         `platform config fetch failed, using cached version ${cached.version}: ${String(err)}`,
       );
       applyToOpenClawConfig(configPath, cached.config, credentials);
+      applyChannelCapabilitySnapshot(stateDir, cached.config, log);
       return;
     }
     // No cache and fetch fails — degrade gracefully
@@ -216,6 +252,7 @@ export async function fetchAndApplyPlatformConfig(opts: ConfigManagerOpts): Prom
     log?.info('platform config unchanged (304)');
     if (cached) {
       applyToOpenClawConfig(configPath, cached.config, credentials);
+      applyChannelCapabilitySnapshot(stateDir, cached.config, log);
     }
     return;
   }
@@ -228,6 +265,7 @@ export async function fetchAndApplyPlatformConfig(opts: ConfigManagerOpts): Prom
     );
     if (cached) {
       applyToOpenClawConfig(configPath, cached.config, credentials);
+      applyChannelCapabilitySnapshot(stateDir, cached.config, log);
     }
     return;
   }
@@ -235,5 +273,6 @@ export async function fetchAndApplyPlatformConfig(opts: ConfigManagerOpts): Prom
   // 5. Newer config received — save cache and apply
   log?.info(`platform config updated to version ${fresh.version}`);
   saveCachedConfig(stateDir, fresh);
+  applyChannelCapabilitySnapshot(stateDir, fresh.config, log);
   applyToOpenClawConfig(configPath, fresh.config, credentials);
 }

package/src/gateway.ts

@@ -5,6 +5,7 @@ import type { ChannelPlugin } from 'openclaw/plugin-sdk/core';
 type ChannelGatewayAdapter<T = unknown> = NonNullable<ChannelPlugin<T>['gateway']>;
 import {
   ParallAgentGateway,
+  capabilityBinDir,
   parseShutdownDeadlineMs,
   parseForkDeadlineMs,
   parseDispatchDeadlineMs,
@@ -35,7 +36,7 @@ import {
 } from './runtime.js';
 import { buildOrchestratorSessionKey } from './session.js';
 import type { ResolvedParallAccount } from './types.js';
-import { fetchAndApplyPlatformConfig } from './config-manager.js';
+import { fetchAndApplyPlatformConfig, getChannelCapabilityKeys } from './config-manager.js';
 import { startWikiHelper } from './wiki-helper.js';
 import { SessionManager } from './oc-session.js';
 import {
@@ -406,6 +407,17 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
         process.env.OPENCLAW_STATE_DIR || path.join(process.env.HOME || '/data', '.openclaw');
       const openclawConfigPath = path.join(stateDir, 'openclaw.json');
 
+      // Channel-capability shims resolve ahead of any globally-installed CLI
+      // of the same name. The plugin runs INSIDE the openclaw process, whose
+      // env every exec-tool child inherits — one idempotent prepend here
+      // covers the agent's shell commands for the process lifetime (the
+      // DIRECTORY is constant; its content tracks capability grants).
+      const shimDir = capabilityBinDir(stateDir);
+      const currentPath = process.env.PATH ?? '';
+      if (!currentPath.split(path.delimiter).includes(shimDir)) {
+        process.env.PATH = currentPath ? `${shimDir}${path.delimiter}${currentPath}` : shimDir;
+      }
+
       const configManagerOpts = {
         client,
         stateDir,
@@ -471,6 +483,9 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
         runtimeRef: { hostname: os.hostname(), pid: process.pid },
         dispatchAdapter,
         log: otelLog,
+        // Live capability view for hint routing: the channel reply hint
+        // points at the vendor CLI only while the grant is active.
+        getCapabilityKeys: getChannelCapabilityKeys,
         shutdownDeadlineMs: parseShutdownDeadlineMs(process.env.PRLL_SHUTDOWN_DEADLINE_MS),
         forkDeadlineMs: parseForkDeadlineMs(process.env.PRLL_FORK_DEADLINE_MS),
         dispatchDeadlineMs: parseDispatchDeadlineMs(process.env.PRLL_DISPATCH_DEADLINE_MS),

package/src/hooks.ts

@@ -9,6 +9,7 @@ import {
   recordMessageSend,
   recordNoReply,
 } from '@parall/agent-core';
+import { getChannelCapabilityFragments } from './config-manager.js';
 import { extractAccountIdFromSessionKey } from './session.js';
 import {
   clearDispatchGroupKey,
@@ -127,6 +128,12 @@ export function registerParallHooks(api: OpenClawPluginApi) {
         PRLL_CHANNEL_CONTEXT,
         PRLL_BEHAVIOR,
         PRLL_REFERENCE_GUIDE,
+        // Channel-capability declarations (platform-config
+        // agents.capabilities[]). Evaluated on EVERY prompt build, so a
+        // capability grant/revocation reaches the next turn without any
+        // restart — the openclaw analogue of the CLI bridges' prompt-file
+        // rewrite + respawn.
+        ...getChannelCapabilityFragments(),
       ].join('\n\n'),
     };
   });