@parall/parall 1.42.1 → 1.44.0

package/dist/config-manager.d.ts

@@ -1,4 +1,6 @@
 import type { ParallClient } from '@parall/sdk';
+export declare function getChannelCapabilityFragments(): string[];
+export declare function getChannelCapabilityKeys(): string[];
 interface ConfigManagerOpts {
     client: ParallClient;
     stateDir: string;

package/dist/config-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-manager.d.ts","sourceRoot":"","sources":["../src/config-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAWhD,UAAU,iBAAiB;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CAClG;AAwKD;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDxF"}
+{"version":3,"file":"config-manager.d.ts","sourceRoot":"","sources":["../src/config-manager.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAuBhD,wBAAgB,6BAA6B,IAAI,MAAM,EAAE,CAExD;AAED,wBAAgB,wBAAwB,IAAI,MAAM,EAAE,CAEnD;AAYD,UAAU,iBAAiB;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CAClG;AAwKD;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqDxF"}

package/dist/config-manager.js

@@ -1,5 +1,28 @@
+import { extractCapabilities, materializeChannelCapabilities, } from '@parall/agent-core';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+// 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 = [];
+export function getChannelCapabilityFragments() {
+    return currentCapabilities.map((c) => c.fragment);
+}
+export function getChannelCapabilityKeys() {
+    return currentCapabilities.map((c) => c.key);
+}
+function applyChannelCapabilitySnapshot(stateDir, config, log) {
+    const caps = extractCapabilities(config);
+    materializeChannelCapabilities(stateDir, caps, log);
+    currentCapabilities = caps;
+}
 const CACHE_FILENAME = 'parall-platform-config.json';
 /** Tool names are no longer registered — all operations go through CLI. */
 function cachePath(stateDir) {
@@ -164,6 +187,7 @@ export async function fetchAndApplyPlatformConfig(opts) {
         if (cached) {
             log?.warn(`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
@@ -175,6 +199,7 @@ export async function fetchAndApplyPlatformConfig(opts) {
         log?.info('platform config unchanged (304)');
         if (cached) {
             applyToOpenClawConfig(configPath, cached.config, credentials);
+            applyChannelCapabilitySnapshot(stateDir, cached.config, log);
         }
         return;
     }
@@ -184,11 +209,13 @@ export async function fetchAndApplyPlatformConfig(opts) {
         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);
+            applyChannelCapabilitySnapshot(stateDir, cached.config, log);
         }
         return;
     }
     // 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/dist/gateway.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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,EASL,KAAK,eAAe,EAGrB,MAAM,oBAAoB,CAAC;AAqB5B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA2KxD,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,CAqLtE,CAAC"}

package/dist/gateway.js

@@ -1,4 +1,4 @@
-import { ParallAgentGateway, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, initAgentTelemetry, createOtelLogger, } from '@parall/agent-core';
+import { ParallAgentGateway, capabilityBinDir, dispatchLaneContextDir, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, initAgentTelemetry, createOtelLogger, } from '@parall/agent-core';
 import { appendPreparedLocalAttachmentRefs, ensureLocalAttachmentGitExclude, pinLocalAttachmentPaths, } from '@parall/agent-core/internal/attachment-input';
 import { ApiError, ParallClient, ParallWs } from '@parall/sdk';
 import * as crypto from 'node:crypto';
@@ -7,10 +7,19 @@ import * as path from 'node:path';
 import { resolveParallAccount } from './accounts.js';
 import { getParallRuntime, removeParallAccountState, setAgentIdentity, setAgentSessionBinding, setDispatchGroupKey, setParallAccountState, } from './runtime.js';
 import { buildOrchestratorSessionKey } from './session.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 { cleanupForkSession, clearSessionState, forkOrchestratorSession, resolveSessionId, resolveTranscriptFile, } from './fork.js';
+/**
+ * Per-session dispatch context file (PRLL_CONTEXT_FILE contract) — same
+ * encoding as the claude/codex bridges: base64url(sessionKey) under the
+ * state dir's dispatch-context/.
+ */
+function sessionContextFilePath(stateDir, sessionKey) {
+    const fileName = Buffer.from(sessionKey).toString('base64url');
+    return path.join(stateDir, 'dispatch-context', `${fileName}.json`);
+}
 function resolveWsUrl(account) {
     if (account.config.ws_url)
         return account.config.ws_url;
@@ -332,6 +341,16 @@ export const parallGateway = {
         try {
             const stateDir = 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,
@@ -394,7 +413,22 @@ export const parallGateway = {
                 runtimeKey: orchestratorKey,
                 runtimeRef: { hostname: os.hostname(), pid: process.pid },
                 dispatchAdapter,
+                // Opts openclaw into the dispatch ledger (claim/fold/complete +
+                // idempotent reply effects) — the same shared-gateway machinery
+                // claude/codex ride; openclaw stays buffer-only (no mid-turn steer),
+                // which the ledger does not require. Replies already flow through
+                // @parall/cli, which reads PRLL_CONTEXT_DIR (injected in hooks.ts)
+                // to bind dispatch_lane + reply effect keys.
+                // Design: docs/engineering-design/dispatch-convergence-design.md §7 (S2).
+                dispatchContextDir: dispatchLaneContextDir(stateDir),
+                // Per-session context file (PRLL_CONTEXT_FILE contract) — the CLI's
+                // TYPED dispatch binding (parall tasks update → task_update effect)
+                // reads lane/event/task fields from this file, not the lane dir.
+                contextFilePathForSession: (sessionKey) => sessionContextFilePath(stateDir, sessionKey),
                 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),
@@ -415,6 +449,12 @@ export const parallGateway = {
                         wikiMountRoot,
                         ws,
                         orchestratorSessionKey: orchestratorKey,
+                        dispatchContextDir: dispatchLaneContextDir(stateDir),
+                        contextFilePathForSession: (sessionKey) => sessionContextFilePath(stateDir, sessionKey),
+                        // Lease-renewal bridge: openclaw tool calls flow through hooks,
+                        // not the RuntimeEvent stream, so hook activity must renew the
+                        // ledger lanes or a long exec outlives the lease (STALE_LANE).
+                        touchRuntimeActivity: (sessionKey) => gateway.touchRuntimeActivity(sessionKey),
                     });
                 },
                 onSessionBinding: async ({ sessionKey, agentSessionId }) => {

package/dist/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AA+G7D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,iBAAiB,QA6KzD"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAgH7D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,iBAAiB,QA+OzD"}

package/dist/hooks.js

@@ -1,4 +1,5 @@
 import { PRLL_BEHAVIOR, PRLL_REFERENCE_GUIDE, buildIdentity, isParallSendCommand, isParallNoReplyCommand, recordToolCall, recordMessageSend, recordNoReply, } from '@parall/agent-core';
+import { getChannelCapabilityFragments } from './config-manager.js';
 import { extractAccountIdFromSessionKey } from './session.js';
 import { clearDispatchGroupKey, getAgentIdentity, getAgentSessionBinding, getDispatchGroupKey, getDispatchMessageId, getParallAccountState, getSessionChatId, setAgentSessionBinding, } from './runtime.js';
 import { resolveSessionId } from './fork.js';
@@ -107,10 +108,55 @@ export function registerParallHooks(api) {
                 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'),
         };
     });
     const pendingSendCalls = new Map();
+    // Lane lease keepalive across the tool-call lifecycle. OpenClaw tool calls
+    // bypass the RuntimeEvent stream, so lane renewal must ride these hooks —
+    // and a ONE-SHOT touch at tool start is not enough: a single exec running
+    // past the lane TTL (10min server-side) would still be dethroned mid-call
+    // and the eventual CLI reply would die with STALE_LANE. While any tool call
+    // is in flight for a session, an unref'd interval keeps touching; the
+    // half-TTL throttle in the ledger decides when a real heartbeat is sent.
+    const laneRenewals = new Map();
+    const LANE_RENEW_INTERVAL_MS = 180_000;
+    const beginToolRenewal = (sessionKey) => {
+        const accountId = extractAccountIdFromSessionKey(sessionKey);
+        const state = accountId ? getParallAccountState(accountId) : undefined;
+        if (!state?.touchRuntimeActivity)
+            return;
+        state.touchRuntimeActivity(sessionKey);
+        const entry = laneRenewals.get(sessionKey) ?? { count: 0 };
+        entry.count++;
+        if (!entry.timer) {
+            entry.timer = setInterval(() => state.touchRuntimeActivity?.(sessionKey), LANE_RENEW_INTERVAL_MS);
+            entry.timer.unref?.();
+        }
+        laneRenewals.set(sessionKey, entry);
+    };
+    const endToolRenewal = (sessionKey) => {
+        const entry = laneRenewals.get(sessionKey);
+        if (entry) {
+            entry.count--;
+            if (entry.count <= 0) {
+                if (entry.timer)
+                    clearInterval(entry.timer);
+                laneRenewals.delete(sessionKey);
+            }
+        }
+        const accountId = extractAccountIdFromSessionKey(sessionKey);
+        const state = accountId ? getParallAccountState(accountId) : undefined;
+        // Final touch on completion — covers the reply window right after a
+        // long tool call ends.
+        state?.touchRuntimeActivity?.(sessionKey);
+    };
     // before_tool_call -> (1) update dispatch metrics, (2) await step creation, (3) ENV injection
     // OpenClaw tool calls bypass the RuntimeEvent stream (they go through hooks, not the
     // gateway-base for-await loop), so dispatch metrics must be updated here as well.
@@ -118,6 +164,9 @@ export function registerParallHooks(api) {
         const sessionKey = ctx.sessionKey;
         if (sessionKey) {
             recordToolCall(sessionKey);
+            // Every tool (not just exec) keeps the ledger lane alive for its
+            // whole lifetime — see laneRenewals above.
+            beginToolRenewal(sessionKey);
             if (event.toolName === 'exec' && event.toolCallId) {
                 const command = event.params?.command;
                 if (isParallSendCommand(command)) {
@@ -202,6 +251,20 @@ export function registerParallHooks(api) {
             injectedEnv.PRLL_TRIGGER_MESSAGE_ID = triggerMsgId;
         if (state.wikiMountRoot)
             injectedEnv.PRLL_WIKI_MOUNT_ROOT = state.wikiMountRoot;
+        // Dispatch-ledger contract: the CLI keys into this directory by send
+        // target to bind dispatch_lane + the reply:<dsp> effect key (idempotent
+        // replies). Set only when the gateway runs the ledger.
+        if (state.dispatchContextDir)
+            injectedEnv.PRLL_CONTEXT_DIR = state.dispatchContextDir;
+        // Per-session context file — the CLI's TYPED binding (parall tasks
+        // update → task_update:<dsp> effect) reads lane/event/task from here.
+        if (state.contextFilePathForSession) {
+            injectedEnv.PRLL_CONTEXT_FILE = state.contextFilePathForSession(sessionKey);
+        }
+        // Long tool calls bypass the RuntimeEvent stream — forward activity so
+        // the ledger lane lease renews (a >TTL exec would otherwise be dethroned
+        // mid-turn and the eventual CLI reply would die with STALE_LANE).
+        state.touchRuntimeActivity?.(sessionKey);
         // OpenClaw context (upstream doesn't inject these into exec env yet)
         injectedEnv.OPENCLAW_SESSION_KEY = sessionKey;
         if (event.toolCallId)
@@ -216,6 +279,8 @@ export function registerParallHooks(api) {
     });
     // after_tool_call -> track CLI outcomes + send tool_result step to AgentSession
     api.on('after_tool_call', async (event, ctx) => {
+        if (ctx.sessionKey)
+            endToolRenewal(ctx.sessionKey);
         if (ctx.sessionKey && event.toolCallId && pendingSendCalls.delete(event.toolCallId)) {
             recordMessageSend(ctx.sessionKey, !event.error);
         }