@parall/parall 1.43.0 → 1.45.0

package/dist/runtime.d.ts

@@ -16,6 +16,23 @@ export type ParallAccountState = {
     wikiMountRoot?: string;
     ws?: ParallWs;
     orchestratorSessionKey?: string;
+    /**
+     * Per-lane dispatch context dir (PRLL_CONTEXT_DIR contract) — set when the
+     * gateway runs the dispatch ledger; hooks inject it into exec env so the
+     * CLI binds replies to their dispatch lane.
+     */
+    dispatchContextDir?: string;
+    /**
+     * Per-session dispatch context file resolver (PRLL_CONTEXT_FILE contract)
+     * — the CLI's typed dispatch binding (task_update effects) reads from it.
+     */
+    contextFilePathForSession?: (sessionKey: string) => string;
+    /**
+     * Lease-renewal bridge into the gateway: openclaw tool activity flows
+     * through hooks (not the RuntimeEvent stream), so hooks must forward it or
+     * a long exec outlives the lane lease.
+     */
+    touchRuntimeActivity?: (sessionKey: string) => void;
     [key: string]: unknown;
 };
 export declare function setParallRuntime(next: PluginRuntime): void;

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAIF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,QAEnD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD;AAKD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,QAEjF;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,QAEzD;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAEvF;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,QAOvB;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEhG;AAED,wBAAgB,yBAAyB,IAAI,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAEnF;AAID,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,QAEvD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,yBAAyB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3D;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAIF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,QAEnD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD;AAKD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,QAEjF;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,QAEzD;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAEvF;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,QAOvB;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEhG;AAED,wBAAgB,yBAAyB,IAAI,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAEnF;AAID,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,QAEvD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D"}

package/package.json

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

package/skills/parall-schedules/SKILL.md

@@ -40,7 +40,7 @@ parall schedules create \
   --run-at <FUTURE_RFC3339_TIME>
 ```
 
-`--target-ids` is who receives the fire (usually yourself when you're self-scheduling; another agent or human when delegating). `--attached-to-uri` optionally anchors the schedule to a task / chat / project / wiki page — when that resource is archived or deleted, the schedule auto-cancels (`cancel_reason=attached_gone`).
+`--target-ids` is who receives the fire (usually yourself when you're self-scheduling; another agent or human when delegating). `--attached-to-uri` optionally anchors the schedule to a task / chat / project / wiki page — when that resource is archived or deleted, the schedule auto-cancels (`status_reason=attached_gone`). A schedule whose agent targets all sit on a terminated machine is auto-paused by the platform (`status_reason=attendee_unreachable`) instead of firing into a void; resuming a recurring schedule while the machine is still terminated just pauses it again on the next slot (a one-shot resumed past its catch-up window instead follows the normal missed semantics and completes).
 
 ### Reminders for someone else
 

package/skills/parall-tasks/SKILL.md

@@ -39,16 +39,32 @@ parall tasks list --assignee-id prll://usr_xxx   # first page only (default 20)
 parall tasks subtasks prll://tsk_xxx             # children of a single parent task
 
 # Create a task (add --parent-id to make it a SUBTASK of another task)
-parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx]
+parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx] [--due-date 2026-08-01]
 
-# Update task status
-parall tasks update prll://tsk_xxx --status in_progress
-parall tasks update prll://tsk_xxx --status done
+# Update task status — add --placement end so the task lands at the end of
+# its NEW status column (a bare --status keeps the old column's sort_order)
+parall tasks update prll://tsk_xxx --status in_progress --placement end
+parall tasks update prll://tsk_xxx --status done --placement end
+
+# Due date — a plain YYYY-MM-DD date (no timestamps); "none" clears it
+parall tasks update prll://tsk_xxx --due-date 2026-08-01
+parall tasks update prll://tsk_xxx --due-date none
+
+# Move a task to the end of its status column
+parall tasks update prll://tsk_xxx --placement end
 
 # Add a comment
 parall tasks comments add prll://tsk_xxx --body "Progress update..."
 ```
 
+Ordering: to append a task to the end of a status column, always use
+`--placement end` — the server resolves the position atomically. This
+includes status changes: a bare `--status` keeps the task's old
+`sort_order`, which may collide inside the new column. Do NOT compute a
+`sort_order` value yourself from listed tasks (your view may be stale or
+partial). `--sort-order` is only for pinpoint insertion between two cards
+you just listed, and it cannot be combined with `--placement`.
+
 Subtasks are just tasks with a parent: create one with `tasks create --parent-id`,
 re-parent with `tasks update --parent-id`, list a parent's children with
 `tasks subtasks`. `tasks list` without `--parent-id` already returns both
@@ -83,7 +99,7 @@ watcher.
 When you receive `[Event: task.assigned]`:
 
 1. Acknowledge with a comment: `tasks comments add prll://tsk_xxx --body "On it"`
-2. Update status: `tasks update prll://tsk_xxx --status in_progress`
+2. Update status: `tasks update prll://tsk_xxx --status in_progress --placement end`
 3. Do the work
 4. Report results in a comment. If a gate remains — review, merge, deploy,
    requester acceptance — set `in_review` and name the gate; set `done`

package/src/gateway.ts

@@ -6,6 +6,7 @@ type ChannelGatewayAdapter<T = unknown> = NonNullable<ChannelPlugin<T>['gateway'
 import {
   ParallAgentGateway,
   capabilityBinDir,
+  dispatchLaneContextDir,
   parseShutdownDeadlineMs,
   parseForkDeadlineMs,
   parseDispatchDeadlineMs,
@@ -47,6 +48,16 @@ import {
   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: string, sessionKey: string): string {
+  const fileName = Buffer.from(sessionKey).toString('base64url');
+  return path.join(stateDir, 'dispatch-context', `${fileName}.json`);
+}
+
 function resolveWsUrl(account: ResolvedParallAccount): string {
   if (account.config.ws_url) return account.config.ws_url;
   const base = account.config.parall_url.replace(/\/$/, '');
@@ -482,6 +493,19 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
         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: string) =>
+          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.
@@ -506,6 +530,13 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
             wikiMountRoot,
             ws,
             orchestratorSessionKey: orchestratorKey,
+            dispatchContextDir: dispatchLaneContextDir(stateDir),
+            contextFilePathForSession: (sessionKey: string) =>
+              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: string) => gateway.touchRuntimeActivity(sessionKey),
           });
         },
         onSessionBinding: async ({ sessionKey, agentSessionId }) => {

package/src/hooks.ts

@@ -140,6 +140,49 @@ export function registerParallHooks(api: OpenClawPluginApi) {
 
   const pendingSendCalls = new Map<string, boolean>();
 
+  // 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<string, { count: number; timer?: ReturnType<typeof setInterval> }>();
+  const LANE_RENEW_INTERVAL_MS = 180_000;
+
+  const beginToolRenewal = (sessionKey: string) => {
+    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: string) => {
+    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.
@@ -147,6 +190,9 @@ export function registerParallHooks(api: OpenClawPluginApi) {
     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 as Record<string, unknown>)?.command as string | undefined;
         if (isParallSendCommand(command)) {
@@ -228,6 +274,19 @@ export function registerParallHooks(api: OpenClawPluginApi) {
     }
     if (triggerMsgId) 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;
@@ -247,6 +306,7 @@ export function registerParallHooks(api: OpenClawPluginApi) {
 
   // 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);
     }

package/src/runtime.ts

@@ -32,6 +32,23 @@ export type ParallAccountState = {
   wikiMountRoot?: string;
   ws?: ParallWs;
   orchestratorSessionKey?: string;
+  /**
+   * Per-lane dispatch context dir (PRLL_CONTEXT_DIR contract) — set when the
+   * gateway runs the dispatch ledger; hooks inject it into exec env so the
+   * CLI binds replies to their dispatch lane.
+   */
+  dispatchContextDir?: string;
+  /**
+   * Per-session dispatch context file resolver (PRLL_CONTEXT_FILE contract)
+   * — the CLI's typed dispatch binding (task_update effects) reads from it.
+   */
+  contextFilePathForSession?: (sessionKey: string) => string;
+  /**
+   * Lease-renewal bridge into the gateway: openclaw tool activity flows
+   * through hooks (not the RuntimeEvent stream), so hooks must forward it or
+   * a long exec outlives the lane lease.
+   */
+  touchRuntimeActivity?: (sessionKey: string) => void;
   [key: string]: unknown;
 };