@parall/cli 1.37.0 → 1.38.0

package/dist/commands/chats.js

@@ -120,7 +120,7 @@ export function registerChatCommands(program) {
         .action(async (chatId, opts) => {
         try {
             if (opts.role !== undefined && opts.role !== 'member') {
-                throw new Error('--role only supports "member"; update the role after adding the member');
+                throw new Error('--role only supports "member"; the CLI cannot change member roles');
             }
             const { client, orgId } = resolveCredentials();
             await client.addChatMember(orgId, stripPrllScheme(chatId), stripPrllScheme(opts.userId));

package/dist/commands/messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/commands/messages.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,QA0JvD"}
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/commands/messages.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,QA8MvD"}

package/dist/commands/messages.js

@@ -1,5 +1,6 @@
 import { ApiError } from '@parall/sdk';
-import { resolveCredentials, resolveRuntimeContext } from '../lib/client.js';
+import { randomUUID } from 'node:crypto';
+import { LaneContextError, markLaneReplyCommitted, resolveCredentials, resolveLaneDispatchContext, resolveRuntimeContext, } from '../lib/client.js';
 import { printError, printJson, printRefHint, stripPrllScheme } from '../lib/output.js';
 import { NO_BODY_ERROR, resolveMessageText, TEXT_FILE_OPTION_DESC, TEXT_OPTION_DESC, } from '../lib/text-input.js';
 import { uploadFile } from '../lib/upload.js';
@@ -98,19 +99,59 @@ export function registerMessageCommands(program) {
             };
             if (attachmentIds)
                 req.attachment_ids = attachmentIds;
-            if (opts.threadRootId !== undefined)
-                req.thread_root_id = stripPrllScheme(opts.threadRootId);
+            const threadRootId = opts.threadRootId !== undefined ? stripPrllScheme(opts.threadRootId) : undefined;
+            if (threadRootId !== undefined)
+                req.thread_root_id = threadRootId;
             if (opts.reply === false)
                 req.hints = { no_reply: true };
             if (ctx.stepId)
                 req.agent_step_id = ctx.stepId;
             if (ctx.sessionId)
                 req.agent_session_id = ctx.sessionId;
-            const result = await client.sendMessage(orgId, chatId, req);
+            // Dispatch lane binding (PRLL_CONTEXT_DIR contract): a send whose
+            // exact (chat, thread) target has an active lane context rides the
+            // server's dispatch ledger — the lane token authorizes the write,
+            // and the FIRST conversational reply of the lane carries the
+            // reply:<dispatch_event_id> effect key so it resolves the dispatched
+            // work in the same transaction. Later sends in the same turn (and
+            // cross-chat sends, which find no lane context) use a random
+            // per-invocation idempotency key. All of this stays out of the
+            // model's view.
+            const laneCtx = resolveLaneDispatchContext(chatId, threadRootId);
+            let usedReplyKey = false;
+            if (laneCtx) {
+                req.dispatch_lane = laneCtx.lane;
+                if (laneCtx.dispatchEventId && !laneCtx.replyCommitted) {
+                    req.idempotency_key = `reply:${laneCtx.dispatchEventId}`;
+                    usedReplyKey = true;
+                }
+                else {
+                    req.idempotency_key = `cli:${randomUUID()}`;
+                }
+                if (!req.agent_step_id && laneCtx.stepId)
+                    req.agent_step_id = laneCtx.stepId;
+                if (!req.agent_session_id && laneCtx.sessionId)
+                    req.agent_session_id = laneCtx.sessionId;
+            }
+            const { message: result, deduplicated } = await client.sendMessageDetailed(orgId, chatId, req);
+            if (laneCtx && usedReplyKey) {
+                markLaneReplyCommitted(laneCtx);
+            }
             printJson(result);
+            if (deduplicated && usedReplyKey) {
+                console.error('Note: this reply was already sent by a previous run (deduplicated) — do not resend it.');
+            }
             printRefHint(result.id, 'Sent');
         }
         catch (err) {
+            if (err instanceof ApiError && err.code === 'STALE_LANE') {
+                printError(new ApiError(err.status, 'Your processing slot was taken over by a newer run — stop working on this conversation.', 'STALE_LANE'));
+                return;
+            }
+            if (err instanceof LaneContextError) {
+                printError(err);
+                return;
+            }
             printError(err);
         }
     });

package/dist/commands/tasks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/commands/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QA6UpD"}
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/commands/tasks.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QAsWpD"}

package/dist/commands/tasks.js

@@ -1,4 +1,5 @@
-import { resolveCredentials } from '../lib/client.js';
+import { ApiError } from '@parall/sdk';
+import { resolveCredentials, resolveTypedDispatchBinding } from '../lib/client.js';
 import { printJson, printError, printRefHint, stripPrllScheme } from '../lib/output.js';
 function stripUndefined(obj) {
     return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
@@ -113,10 +114,30 @@ export function registerTaskCommands(program) {
             if (Object.keys(data).length === 0) {
                 printError(new Error('No fields to update. Provide at least one option.'));
             }
-            const result = await client.updateTask(orgId, taskId, data);
+            // Typed dispatch binding: when this turn is a typed dispatch about
+            // exactly this task, the update rides the claimed typed lane; the
+            // first update also carries the canonical task_update:<dsp> effect
+            // key so it resolves the dispatched work in the same transaction.
+            // Invisible to the model — same contract as message replies.
+            const binding = resolveTypedDispatchBinding(taskId);
+            const req = { ...data };
+            if (binding) {
+                req.dispatch_lane = binding.lane;
+                req.dispatch_event_id = binding.dispatchEventId;
+                if (binding.effectKey)
+                    req.dispatch_effect_key = binding.effectKey;
+            }
+            const result = await client.updateTask(orgId, taskId, req);
+            if (binding?.effectKey) {
+                binding.markCommitted();
+            }
             printJson(result);
         }
         catch (err) {
+            if (err instanceof ApiError && err.code === 'STALE_LANE') {
+                printError(new ApiError(err.status, 'Your processing slot was taken over by a newer run — stop working on this task.', 'STALE_LANE'));
+                return;
+            }
             printError(err);
         }
     });

package/dist/lib/client.d.ts

@@ -11,6 +11,12 @@ export type RuntimeContext = {
     triggerMessageId?: string;
     /** When true, CLI should not send automatic reply messages — the bridge handles text projection. */
     noReply: boolean;
+    /** Dispatch ledger binding of the current turn (additive; bridge-written). */
+    dispatchEventId?: string;
+    lane?: string;
+    laneTargetUri?: string;
+    /** Typed binding hint: the task this dispatch is about (task dispatch turns only). */
+    taskId?: string;
 };
 /**
  * Read per-dispatch context from ENV + sideband files.
@@ -21,5 +27,60 @@ export type RuntimeContext = {
  * 3. PRLL_STEP_ID_FILE plain text (legacy step-id-only backward compat)
  */
 export declare function resolveRuntimeContext(): RuntimeContext;
+/** Typed dispatch binding for a task write, derived from the turn context. */
+export type TypedDispatchBinding = {
+    lane: string;
+    dispatchEventId: string;
+    /** Set for the first (resolving) update of this dispatch. */
+    effectKey?: string;
+    markCommitted: () => void;
+};
+/**
+ * Resolve the typed-lane binding for `parall task update <taskId>`: the
+ * current turn must be a typed dispatch (lane target `dsp:<id>`) about this
+ * exact task. The first update carries the canonical
+ * `task_update:<dispatch_event_id>` effect key (resolves the WorkItem in the
+ * same transaction); later updates go keyless (lane-checked only). The
+ * committed flag lives in a CLI-owned sidecar keyed by the typed lane; when
+ * PRLL_CONTEXT_DIR is absent the sidecar can't exist, so no effect key is
+ * ever attached (a blind key would make a *different* second update replay
+ * the first one's result instead of applying).
+ */
+export declare function resolveTypedDispatchBinding(taskId: string): TypedDispatchBinding | null;
+/** Per-lane dispatch context (PRLL_CONTEXT_DIR contract), keyed by send target. */
+export type LaneDispatchContext = {
+    lane: string;
+    dispatchEventId?: string;
+    targetUri: string;
+    threadRootId?: string;
+    sessionId?: string;
+    stepId?: string;
+    /** True when the reply slot for this lane was already consumed (sidecar). */
+    replyCommitted: boolean;
+    replyStatePath: string;
+};
+/**
+ * Error thrown when a lane context file exists for the send target but lacks
+ * the dispatch/lane fields — the strong-idempotency path must fail closed
+ * rather than silently degrade to a best-effort write.
+ */
+export declare class LaneContextError extends Error {
+}
+/**
+ * Look up the dispatch lane context for a send target under the
+ * PRLL_CONTEXT_DIR contract. Returns null when the contract is not in effect
+ * (env unset) or no lane file exists for this exact (target, thread) — i.e.
+ * a cross-chat / non-dispatch send, which stays on the best-effort path.
+ *
+ * The lane key encodes the full lane identity: a thread send only matches a
+ * thread lane, a channel send only a channel lane.
+ */
+export declare function resolveLaneDispatchContext(chatId: string, threadRootId?: string): LaneDispatchContext | null;
+/**
+ * Record that this lane's first conversational reply has been committed. The
+ * sidecar is CLI-owned — never the bridge-owned context file, which the
+ * bridge rewrites throughout the turn and would clobber inline state.
+ */
+export declare function markLaneReplyCommitted(laneCtx: LaneDispatchContext): void;
 export declare function resolveCredentials(): ResolvedCredentials;
 //# sourceMappingURL=client.d.ts.map

package/dist/lib/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oGAAoG;IACpG,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,CAiCtD;AAED,wBAAgB,kBAAkB,IAAI,mBAAmB,CA8BxD"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oGAAoG;IACpG,OAAO,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,CAmDtD;AAED,8EAA8E;AAC9E,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAwCvF;AAED,mFAAmF;AACnF,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAE9C;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,GACpB,mBAAmB,GAAG,IAAI,CA+E5B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAYzE;AAED,wBAAgB,kBAAkB,IAAI,mBAAmB,CA8BxD"}

package/dist/lib/client.js

@@ -1,4 +1,5 @@
 import * as fs from 'node:fs';
+import { laneContextFilePath, laneReplyStateFilePath } from '@parall/agent-core';
 import { ParallClient } from '@parall/sdk';
 /**
  * Read per-dispatch context from ENV + sideband files.
@@ -14,6 +15,10 @@ export function resolveRuntimeContext() {
     let chatId = process.env.PRLL_CHAT_ID?.trim() || undefined;
     let triggerMessageId = process.env.PRLL_TRIGGER_MESSAGE_ID?.trim() || undefined;
     let noReply = process.env.PRLL_NO_REPLY === '1';
+    let dispatchEventId;
+    let lane;
+    let laneTargetUri;
+    let taskId;
     if (process.env.PRLL_CONTEXT_FILE) {
         try {
             const raw = fs.readFileSync(process.env.PRLL_CONTEXT_FILE, 'utf-8').trim();
@@ -25,6 +30,10 @@ export function resolveRuntimeContext() {
                 stepId ??= ctx.step_id || undefined;
                 if (ctx.no_reply === true)
                     noReply = true;
+                dispatchEventId = ctx.dispatch_event_id || undefined;
+                lane = ctx.lane || undefined;
+                laneTargetUri = ctx.target_uri || undefined;
+                taskId = ctx.task_id || undefined;
             }
         }
         catch {
@@ -41,7 +50,170 @@ export function resolveRuntimeContext() {
             // File not yet written or unreadable — no step context
         }
     }
-    return { sessionId, stepId, chatId, triggerMessageId, noReply };
+    return {
+        sessionId,
+        stepId,
+        chatId,
+        triggerMessageId,
+        noReply,
+        dispatchEventId,
+        lane,
+        laneTargetUri,
+        taskId,
+    };
+}
+/**
+ * Resolve the typed-lane binding for `parall task update <taskId>`: the
+ * current turn must be a typed dispatch (lane target `dsp:<id>`) about this
+ * exact task. The first update carries the canonical
+ * `task_update:<dispatch_event_id>` effect key (resolves the WorkItem in the
+ * same transaction); later updates go keyless (lane-checked only). The
+ * committed flag lives in a CLI-owned sidecar keyed by the typed lane; when
+ * PRLL_CONTEXT_DIR is absent the sidecar can't exist, so no effect key is
+ * ever attached (a blind key would make a *different* second update replay
+ * the first one's result instead of applying).
+ */
+export function resolveTypedDispatchBinding(taskId) {
+    const ctx = resolveRuntimeContext();
+    if (!ctx.lane || !ctx.dispatchEventId)
+        return null;
+    if (!ctx.laneTargetUri?.startsWith('dsp:'))
+        return null;
+    if (!ctx.taskId || ctx.taskId !== taskId)
+        return null;
+    const binding = {
+        lane: ctx.lane,
+        dispatchEventId: ctx.dispatchEventId,
+        markCommitted: () => { },
+    };
+    const contextDir = process.env.PRLL_CONTEXT_DIR?.trim();
+    if (!contextDir)
+        return binding;
+    const sidecarPath = laneReplyStateFilePath(contextDir, ctx.laneTargetUri);
+    let committed = false;
+    try {
+        const sidecar = JSON.parse(fs.readFileSync(sidecarPath, 'utf-8'));
+        committed =
+            sidecar.reply_committed === true && sidecar.dispatch_event_id === ctx.dispatchEventId;
+    }
+    catch {
+        // No sidecar yet — resolving update not committed.
+    }
+    if (!committed) {
+        const dispatchEventId = ctx.dispatchEventId;
+        binding.effectKey = `task_update:${dispatchEventId}`;
+        binding.markCommitted = () => {
+            try {
+                fs.writeFileSync(sidecarPath, JSON.stringify({ dispatch_event_id: dispatchEventId, reply_committed: true }), 'utf-8');
+            }
+            catch {
+                // Best-effort — a lost sidecar means the next update retries the key
+                // and the server's effect ledger replies idempotently.
+            }
+        };
+    }
+    return binding;
+}
+/**
+ * Error thrown when a lane context file exists for the send target but lacks
+ * the dispatch/lane fields — the strong-idempotency path must fail closed
+ * rather than silently degrade to a best-effort write.
+ */
+export class LaneContextError extends Error {
+}
+/**
+ * Look up the dispatch lane context for a send target under the
+ * PRLL_CONTEXT_DIR contract. Returns null when the contract is not in effect
+ * (env unset) or no lane file exists for this exact (target, thread) — i.e.
+ * a cross-chat / non-dispatch send, which stays on the best-effort path.
+ *
+ * The lane key encodes the full lane identity: a thread send only matches a
+ * thread lane, a channel send only a channel lane.
+ */
+export function resolveLaneDispatchContext(chatId, threadRootId) {
+    const contextDir = process.env.PRLL_CONTEXT_DIR?.trim();
+    if (!contextDir)
+        return null;
+    const targetUri = `prll://${chatId}`;
+    const filePath = laneContextFilePath(contextDir, targetUri, threadRootId);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf-8').trim();
+    }
+    catch (err) {
+        // Only a genuinely-absent file means "not a dispatch-bound send".
+        // Permission errors etc. must fail closed, not silently degrade the
+        // write out of the ledger.
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return null;
+        throw new LaneContextError(`Dispatch context for ${targetUri} is unreadable (${filePath}) — retry, or escalate if this persists`);
+    }
+    if (!raw) {
+        throw new LaneContextError(`Dispatch context for ${targetUri} is empty (${filePath}) — retry, or escalate if this persists`);
+    }
+    let ctx;
+    try {
+        ctx = JSON.parse(raw);
+    }
+    catch {
+        throw new LaneContextError(`Dispatch context for ${targetUri} is unreadable (${filePath}) — retry, or escalate if this persists`);
+    }
+    const lane = typeof ctx.lane === 'string' && ctx.lane ? ctx.lane : undefined;
+    if (!lane) {
+        // File exists but the lane fields are missing: fail closed instead of
+        // silently writing a side effect outside the ledger.
+        throw new LaneContextError(`Dispatch context for ${targetUri} is missing its lane binding — retry, or escalate if this persists`);
+    }
+    const dispatchEventId = typeof ctx.dispatch_event_id === 'string' && ctx.dispatch_event_id
+        ? ctx.dispatch_event_id
+        : undefined;
+    if (!dispatchEventId) {
+        // The bridge folds every group member before dispatching (fail-closed
+        // ensureLane), so a lane context without its trigger WorkItem id is
+        // corruption — never a legitimate degraded state.
+        throw new LaneContextError(`Dispatch context for ${targetUri} is missing its dispatch_event_id — retry, or escalate if this persists`);
+    }
+    const replyStatePath = laneReplyStateFilePath(contextDir, targetUri, threadRootId);
+    let replyCommitted = false;
+    try {
+        const sidecar = JSON.parse(fs.readFileSync(replyStatePath, 'utf-8'));
+        // The sidecar only counts for the same trigger — a new turn (new
+        // dispatch_event_id) resets the reply slot.
+        replyCommitted =
+            sidecar.reply_committed === true &&
+                dispatchEventId != null &&
+                sidecar.dispatch_event_id === dispatchEventId;
+    }
+    catch {
+        // No sidecar yet — reply slot unused.
+    }
+    return {
+        lane,
+        dispatchEventId,
+        targetUri,
+        threadRootId,
+        sessionId: typeof ctx.session_id === 'string' && ctx.session_id ? ctx.session_id : undefined,
+        stepId: typeof ctx.step_id === 'string' && ctx.step_id ? ctx.step_id : undefined,
+        replyCommitted,
+        replyStatePath,
+    };
+}
+/**
+ * Record that this lane's first conversational reply has been committed. The
+ * sidecar is CLI-owned — never the bridge-owned context file, which the
+ * bridge rewrites throughout the turn and would clobber inline state.
+ */
+export function markLaneReplyCommitted(laneCtx) {
+    if (!laneCtx.dispatchEventId)
+        return;
+    try {
+        fs.writeFileSync(laneCtx.replyStatePath, JSON.stringify({ dispatch_event_id: laneCtx.dispatchEventId, reply_committed: true }), 'utf-8');
+    }
+    catch {
+        // Best-effort — a lost sidecar means the next send retries the reply key
+        // and the server's effect ledger dedupes it.
+    }
 }
 export function resolveCredentials() {
     const url = process.env.PRLL_API_URL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/cli",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "description": "CLI client for Parall — universal agent & human access to Parall API",
   "license": "MIT",
   "repository": {
@@ -36,13 +36,14 @@
     "diff": "^8.0.3",
     "js-yaml": "^4.1.0",
     "zod": "^4.3.6",
-    "@parall/sdk": "1.37.0"
+    "@parall/agent-core": "1.38.0",
+    "@parall/sdk": "1.38.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
-    "@parall/agent-core": "1.37.0"
+    "@parall/agent-core": "1.38.0"
   },
   "scripts": {
     "build": "tsc",