@parall/agent-core 1.26.0 → 1.26.2

package/dist/dispatch-adapter.d.ts

@@ -65,6 +65,7 @@ export type ForkSessionHandle = {
 export type ForkOpts = {
     sessionKey: string;
     context: DispatchContext;
+    preDispatchBranchPoint?: string;
 };
 export type CleanupForkOpts = {
     fork: ForkSessionHandle;
@@ -77,5 +78,7 @@ export interface DispatchAdapter {
     forkSession?(opts: ForkOpts): Promise<ForkSessionHandle | null> | ForkSessionHandle | null;
     /** Clean up a fork session created by forkSession(). */
     cleanupFork?(opts: CleanupForkOpts): Promise<void> | void;
+    /** Return the current on-disk branch point (leaf ID) for the given session, if available. */
+    getBranchPoint?(sessionKey: string): string | undefined;
 }
 //# sourceMappingURL=dispatch-adapter.d.ts.map

package/dist/dispatch-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch-adapter.d.ts","sourceRoot":"","sources":["../src/dispatch-adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dispatch-adapter.d.ts","sourceRoot":"","sources":["../src/dispatch-adapter.ts"],"names":[],"mappings":"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"}

package/dist/event-format.d.ts

@@ -1,4 +1,5 @@
 import type { ForkResult, ParallEvent } from "./types.js";
 export declare function buildEventBody(event: ParallEvent): string;
+export declare function buildForkScopePrefix(event: ParallEvent): string;
 export declare function buildForkResultPrefix(results: ForkResult[]): string;
 //# sourceMappingURL=event-format.d.ts.map

package/dist/event-format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-format.d.ts","sourceRoot":"","sources":["../src/event-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAgDzD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CASnE"}
+{"version":3,"file":"event-format.d.ts","sourceRoot":"","sources":["../src/event-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAsDzD;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAK/D;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CASnE"}

package/dist/event-format.js

@@ -37,6 +37,13 @@ export function buildEventBody(event) {
         lines.push(`[Comment ID: prll://${event.messageId}]`);
         lines.push("", event.body);
     }
+    else if (event.type === "approval") {
+        lines.push(`[Event: approval.decided]`);
+        lines.push(`[Approval: prll://${event.messageId}]`);
+        lines.push(`[Chat: prll://${event.targetId}]`);
+        lines.push(`[Decided by: ${event.senderName} (prll://${event.senderId})]`);
+        lines.push("", event.body);
+    }
     else if (event.type === "schedule") {
         lines.push(`[Event: schedule.fired]`);
         lines.push(`[Schedule: prll://${event.targetId}]`);
@@ -58,6 +65,12 @@ export function buildEventBody(event) {
     }
     return lines.join("\n");
 }
+export function buildForkScopePrefix(event) {
+    const targetLabel = event.targetName
+        ? `"${event.targetName}" (prll://${event.targetId})`
+        : `prll://${event.targetId}`;
+    return `[Fork scope: You are a parallel worker handling ${targetLabel} only. The conversation history above is inherited context — do NOT complete unfinished work, retry failed tool calls, or send messages to other chats from that history. Only act on the event below.]\n\n`;
+}
 export function buildForkResultPrefix(results) {
     if (!results.length)
         return "";

package/dist/gateway-base.d.ts

@@ -86,6 +86,7 @@ export declare class ParallAgentGateway {
      */
     private fetchAndHandleScheduleFire;
     private handleScheduleFire;
+    private fetchAndHandleApprovalDecided;
     private catchUpFromDispatch;
     private handleHello;
     private waitForDrain;

package/dist/gateway-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-base.d.ts","sourceRoot":"","sources":["../src/gateway-base.ts"],"names":[],"mappings":"AAIA,OAAO,EAAuB,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EACV,qBAAqB,EAYtB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAEV,eAAe,EAGf,aAAa,EAEd,MAAM,uBAAuB,CAAC;AAoD/B,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,EAAE,EAAE,QAAQ,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,eAAe,EAAE,eAAe,CAAC;IACjC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAI3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yBAAyB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACvE,0FAA0F;IAC1F,wBAAwB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACtE,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,QAAQ,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjH,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACjD,CAAC;AAUF,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAKnF;AAqCD,qBAAa,kBAAkB;IAmCjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAlCjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IACjE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAK5B;IAEF,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAS;IAMzB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,cAAc,CAAyB;IAE/C,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAQ;IAChD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAI9C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;gBAEjB,IAAI,EAAE,oBAAoB;IAKjD,GAAG,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAyHlD,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,oBAAoB;YAoBd,eAAe;YA6Bf,iBAAiB;IA0F/B,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,uBAAuB;IAW/B,kEAAkE;IAClE,OAAO,CAAC,eAAe;IASvB,kEAAkE;IAClE,OAAO,CAAC,eAAe;YAQT,gCAAgC;YAUhC,WAAW;YAiGX,gBAAgB;YAkFhB,eAAe;YA6Ef,kBAAkB;YA+ElB,kBAAkB;YAkBlB,4BAA4B;YAoD5B,aAAa;YA+Bb,oBAAoB;YAoCpB,kBAAkB;YAwBlB,iBAAiB;IAiF/B;;;;;;;OAOG;YACW,0BAA0B;YAsB1B,kBAAkB;YAsClB,mBAAmB;YAkGnB,WAAW;IA6DzB,OAAO,CAAC,YAAY;YAiBN,QAAQ;CA4CvB"}
+{"version":3,"file":"gateway-base.d.ts","sourceRoot":"","sources":["../src/gateway-base.ts"],"names":[],"mappings":"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"}

package/dist/gateway-base.js

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 import { MENTION_ALL_USER_ID } from "@parall/sdk";
-import { buildEventBody, buildForkResultPrefix } from "./event-format.js";
+import { buildEventBody, buildForkResultPrefix, buildForkScopePrefix } from "./event-format.js";
 import { routeTrigger } from "./routing.js";
 import { clearDispatchMessageId, clearDispatchNoReply, clearSessionMessageId, setDispatchMessageId, setDispatchNoReply, setSessionChatId, setSessionMessageId, } from "./session-state.js";
 // Parse PRLL_SHUTDOWN_DEADLINE_MS (or any string env value) into a positive
@@ -192,6 +192,19 @@ export class ParallAgentGateway {
                     this.opts.log?.error(`parall[${this.opts.accountId}]: schedule fire dispatch failed for ${data.source_id}: ${String(err)}`);
                 }
             }
+            else if (data.event_type === "approval_decided") {
+                if (!data.source_id)
+                    return;
+                try {
+                    const dispatched = await this.fetchAndHandleApprovalDecided(data.source_id, data.actor_id, data.chat_id ?? null);
+                    if (dispatched) {
+                        this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => { });
+                    }
+                }
+                catch (err) {
+                    this.opts.log?.error(`parall[${this.opts.accountId}]: approval decided dispatch failed for ${data.source_id}: ${String(err)}`);
+                }
+            }
             else if (data.event_type !== "message" && data.event_type !== "task_assign") {
                 // Truly unknown event_type — log so a newly-added dispatch type
                 // not yet wired here surfaces during runtime testing. "message"
@@ -262,7 +275,7 @@ export class ParallAgentGateway {
             runtimeType: this.opts.runtimeType,
             runtimeKey: this.opts.runtimeKey,
             sessionId: this.activeSessionId,
-            chatId: event.type === "message" ? event.targetId : undefined,
+            chatId: (event.type === "message" || event.type === "approval") ? event.targetId : undefined,
             triggerMessageId: event.messageId,
             noReply: event.noReply ?? false,
             contextFilePath: this.opts.contextFilePathForSession?.(sessionKey),
@@ -284,11 +297,13 @@ export class ParallAgentGateway {
                     trigger_type: event.type === "task" ? "task_assign" :
                         event.type === "task_comment" ? "task_comment" :
                             event.type === "schedule" ? "schedule_fire" :
-                                "mention",
+                                event.type === "approval" ? "approval_decided" :
+                                    "mention",
                     trigger_ref: event.type === "task" ? { task_id: event.targetId } :
                         event.type === "task_comment" ? { comment_id: event.messageId, task_id: event.targetId } :
                             event.type === "schedule" ? { schedule_id: event.targetId, run_id: event.messageId } :
-                                { message_id: event.messageId },
+                                event.type === "approval" ? { approval_id: event.messageId } :
+                                    { message_id: event.messageId },
                     sender_id: event.senderId,
                     sender_name: event.senderName,
                     summary: event.body.substring(0, 200),
@@ -543,7 +558,7 @@ export class ParallAgentGateway {
                 const last = events[events.length - 1];
                 const earlier = events.slice(0, -1);
                 try {
-                    const dispatched = await this.runDispatch(last, fork.fork.sessionKey, buildEventBody(last), earlier);
+                    const dispatched = await this.runDispatch(last, fork.fork.sessionKey, buildForkScopePrefix(last) + buildEventBody(last), earlier);
                     if (!dispatched) {
                         // Shutdown short-circuit — resolve un-acked so the server requeues
                         // for the replacement pod and stop draining further items.
@@ -634,6 +649,8 @@ export class ParallAgentGateway {
                         body: "[Orchestrator: fork session(s) completed — review results above]",
                     };
                     this.dispatchState.mainCurrentTargetId = undefined;
+                    this.dispatchState.mainPreDispatchBranchPoint =
+                        this.opts.dispatchAdapter.getBranchPoint?.(this.opts.runtimeKey);
                     const dispatched = await this.runDispatch(syntheticEvent, this.opts.runtimeKey, forkPrefix + buildEventBody(syntheticEvent));
                     if (!dispatched) {
                         // Shutdown: put the fork results back at the head so the synthetic
@@ -654,8 +671,8 @@ export class ParallAgentGateway {
                 const pendingFork = this.dispatchState.pendingForkResults.splice(0);
                 const forkPrefix = buildForkResultPrefix(pendingFork);
                 this.dispatchState.mainCurrentTargetId = event.targetId;
-                // Earlier-event input steps are persisted inside runDispatch (behind
-                // its shutdown gate) so a shutdown short-circuit cannot leave orphans.
+                this.dispatchState.mainPreDispatchBranchPoint =
+                    this.opts.dispatchAdapter.getBranchPoint?.(this.opts.runtimeKey);
                 const dispatched = await this.runDispatch(event, this.opts.runtimeKey, forkPrefix + buildEventBody(event), earlier);
                 if (!dispatched) {
                     // Shutdown: skip the ack so the server redelivers these buffered
@@ -679,6 +696,7 @@ export class ParallAgentGateway {
             this.draining = false;
             this.dispatchState.mainDispatching = false;
             this.dispatchState.mainCurrentTargetId = undefined;
+            this.dispatchState.mainPreDispatchBranchPoint = undefined;
         }
     }
     async handleInboundEvent(event) {
@@ -689,6 +707,11 @@ export class ParallAgentGateway {
                 const forkPrefix = buildForkResultPrefix(pendingFork);
                 this.dispatchState.mainDispatching = true;
                 this.dispatchState.mainCurrentTargetId = event.targetId;
+                // Snapshot the on-disk branch point BEFORE runDispatch starts writing
+                // to the session file. Fork sessions created while main is in-flight
+                // use this to branch from the clean pre-dispatch state.
+                this.dispatchState.mainPreDispatchBranchPoint =
+                    this.opts.dispatchAdapter.getBranchPoint?.(this.opts.runtimeKey);
                 let dispatched = false;
                 try {
                     dispatched = await this.runDispatch(event, this.opts.runtimeKey, forkPrefix + buildEventBody(event));
@@ -728,6 +751,7 @@ export class ParallAgentGateway {
                 const fork = await this.opts.dispatchAdapter.forkSession({
                     sessionKey: this.opts.runtimeKey,
                     context: this.buildDispatchContext(event, this.opts.runtimeKey),
+                    preDispatchBranchPoint: this.dispatchState.mainPreDispatchBranchPoint,
                 });
                 if (!fork) {
                     this.opts.log?.warn(`parall[${this.opts.accountId}]: fork failed, buffering event for main session`);
@@ -1050,6 +1074,53 @@ export class ParallAgentGateway {
         }
         return dispatched;
     }
+    async fetchAndHandleApprovalDecided(approvalId, actorId, chatId) {
+        let approval = null;
+        try {
+            approval = await this.opts.client.getApproval(approvalId);
+        }
+        catch (err) {
+            const status = err?.status;
+            if (status === 404 || status === 403) {
+                this.opts.log?.warn(`parall[${this.opts.accountId}]: approval ${approvalId} not accessible (${status}), acking stale dispatch`);
+                return true;
+            }
+            this.opts.log?.warn(`parall[${this.opts.accountId}]: approval fetch failed for ${approvalId}, leaving pending: ${String(err)}`);
+            return false;
+        }
+        if (!approval)
+            return true;
+        if (this.shuttingDown)
+            return false;
+        const dedupeKey = `approval:${approval.id}`;
+        if (this.dispatchedTasks.has(dedupeKey))
+            return false;
+        this.dispatchedTasks.add(dedupeKey);
+        this.opts.log?.info(`parall[${this.opts.accountId}]: approval decided: ${approval.id} (${approval.status})`);
+        const statusLabel = approval.status === "approved" ? "Approved" : "Rejected";
+        const execInfo = approval.execution_status ? ` | execution: ${approval.execution_status}` : "";
+        const body = `${statusLabel}: ${approval.title}${execInfo}`;
+        const event = {
+            type: "approval",
+            targetId: chatId ?? approval.chat_id,
+            senderId: actorId ?? approval.decided_by ?? "system",
+            senderName: "approver",
+            messageId: approval.id,
+            body,
+        };
+        let dispatched;
+        try {
+            dispatched = await this.handleInboundEvent(event);
+        }
+        catch (err) {
+            this.dispatchedTasks.delete(dedupeKey);
+            throw err;
+        }
+        if (!dispatched) {
+            this.dispatchedTasks.delete(dedupeKey);
+        }
+        return dispatched;
+    }
     async catchUpFromDispatch(coldStart = false) {
         const minAge = coldStart ? Date.now() - this.COLD_START_WINDOW_MS : 0;
         let cursor;
@@ -1097,6 +1168,9 @@ export class ParallAgentGateway {
                     else if (item.event_type === "schedule.fire" && item.source_id) {
                         dispatched = await this.fetchAndHandleScheduleFire(item.source_id, item.actor_id);
                     }
+                    else if (item.event_type === "approval_decided" && item.source_id) {
+                        dispatched = await this.fetchAndHandleApprovalDecided(item.source_id, item.actor_id, item.chat_id ?? null);
+                    }
                     else if (item.event_type === "message" && item.source_id && item.chat_id) {
                         if (!this.tryClaimMessage(item.source_id))
                             continue;

package/dist/types.d.ts

@@ -15,10 +15,12 @@ export type DispatchState = {
     activeForks: Map<string, string>;
     pendingForkResults: ForkResult[];
     mainBuffer: ParallEvent[];
+    /** Snapshot of the session branch point taken BEFORE runDispatch starts on main. */
+    mainPreDispatchBranchPoint?: string;
 };
 /** Normalized inbound event from Parall. */
 export type ParallEvent = {
-    type: "message" | "task" | "task_comment" | "schedule";
+    type: "message" | "task" | "task_comment" | "schedule" | "approval";
     targetId: string;
     targetName?: string;
     targetType?: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;CAC3B,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,cAAc,GAAG,UAAU,CAAC;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,CAAC;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,cAAc,GAAG,UAAU,GAAG,UAAU,CAAC;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,CAAC;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.26.0",
+  "version": "1.26.2",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,7 @@
     "src"
   ],
   "dependencies": {
-    "@parall/sdk": "1.26.0"
+    "@parall/sdk": "1.26.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/dispatch-adapter.ts

@@ -49,6 +49,7 @@ export type ForkSessionHandle = {
 export type ForkOpts = {
   sessionKey: string;
   context: DispatchContext;
+  preDispatchBranchPoint?: string;
 };
 
 export type CleanupForkOpts = {
@@ -65,4 +66,7 @@ export interface DispatchAdapter {
 
   /** Clean up a fork session created by forkSession(). */
   cleanupFork?(opts: CleanupForkOpts): Promise<void> | void;
+
+  /** Return the current on-disk branch point (leaf ID) for the given session, if available. */
+  getBranchPoint?(sessionKey: string): string | undefined;
 }

package/src/event-format.ts

@@ -35,6 +35,12 @@ export function buildEventBody(event: ParallEvent): string {
     lines.push(`[From: ${event.senderName} (prll://${event.senderId})]`);
     lines.push(`[Comment ID: prll://${event.messageId}]`);
     lines.push("", event.body);
+  } else if (event.type === "approval") {
+    lines.push(`[Event: approval.decided]`);
+    lines.push(`[Approval: prll://${event.messageId}]`);
+    lines.push(`[Chat: prll://${event.targetId}]`);
+    lines.push(`[Decided by: ${event.senderName} (prll://${event.senderId})]`);
+    lines.push("", event.body);
   } else if (event.type === "schedule") {
     lines.push(`[Event: schedule.fired]`);
     lines.push(`[Schedule: prll://${event.targetId}]`);
@@ -54,6 +60,13 @@ export function buildEventBody(event: ParallEvent): string {
   return lines.join("\n");
 }
 
+export function buildForkScopePrefix(event: ParallEvent): string {
+  const targetLabel = event.targetName
+    ? `"${event.targetName}" (prll://${event.targetId})`
+    : `prll://${event.targetId}`;
+  return `[Fork scope: You are a parallel worker handling ${targetLabel} only. The conversation history above is inherited context — do NOT complete unfinished work, retry failed tool calls, or send messages to other chats from that history. Only act on the event below.]\n\n`;
+}
+
 export function buildForkResultPrefix(results: ForkResult[]): string {
   if (!results.length) return "";
   const blocks = results.map((result) => {

package/src/gateway-base.ts

@@ -5,6 +5,7 @@ import { randomUUID } from "node:crypto";
 import { MENTION_ALL_USER_ID, ParallClient, ParallWs } from "@parall/sdk";
 import type {
   AgentConfigUpdateData,
+  Approval,
   Chat,
   ChatUpdateData,
   Comment,
@@ -17,7 +18,7 @@ import type {
   TaskAssignedData,
   TextContent,
 } from "@parall/sdk";
-import { buildEventBody, buildForkResultPrefix } from "./event-format.js";
+import { buildEventBody, buildForkResultPrefix, buildForkScopePrefix } from "./event-format.js";
 import type {
   CleanupForkOpts,
   DispatchAdapter,
@@ -294,6 +295,16 @@ export class ParallAgentGateway {
         } catch (err) {
           this.opts.log?.error(`parall[${this.opts.accountId}]: schedule fire dispatch failed for ${data.source_id}: ${String(err)}`);
         }
+      } else if (data.event_type === "approval_decided") {
+        if (!data.source_id) return;
+        try {
+          const dispatched = await this.fetchAndHandleApprovalDecided(data.source_id, data.actor_id, data.chat_id ?? null);
+          if (dispatched) {
+            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+          }
+        } catch (err) {
+          this.opts.log?.error(`parall[${this.opts.accountId}]: approval decided dispatch failed for ${data.source_id}: ${String(err)}`);
+        }
       } else if (data.event_type !== "message" && data.event_type !== "task_assign") {
         // Truly unknown event_type — log so a newly-added dispatch type
         // not yet wired here surfaces during runtime testing. "message"
@@ -365,7 +376,7 @@ export class ParallAgentGateway {
       runtimeType: this.opts.runtimeType,
       runtimeKey: this.opts.runtimeKey,
       sessionId: this.activeSessionId,
-      chatId: event.type === "message" ? event.targetId : undefined,
+      chatId: (event.type === "message" || event.type === "approval") ? event.targetId : undefined,
       triggerMessageId: event.messageId,
       noReply: event.noReply ?? false,
       contextFilePath: this.opts.contextFilePathForSession?.(sessionKey),
@@ -388,11 +399,13 @@ export class ParallAgentGateway {
             event.type === "task" ? "task_assign" :
             event.type === "task_comment" ? "task_comment" :
             event.type === "schedule" ? "schedule_fire" :
+            event.type === "approval" ? "approval_decided" :
             "mention",
           trigger_ref:
             event.type === "task" ? { task_id: event.targetId } :
             event.type === "task_comment" ? { comment_id: event.messageId, task_id: event.targetId } :
             event.type === "schedule" ? { schedule_id: event.targetId, run_id: event.messageId } :
+            event.type === "approval" ? { approval_id: event.messageId } :
             { message_id: event.messageId },
           sender_id: event.senderId,
           sender_name: event.senderName,
@@ -658,7 +671,7 @@ export class ParallAgentGateway {
         const last = events[events.length - 1];
         const earlier = events.slice(0, -1);
         try {
-          const dispatched = await this.runDispatch(last, fork.fork.sessionKey, buildEventBody(last), earlier);
+          const dispatched = await this.runDispatch(last, fork.fork.sessionKey, buildForkScopePrefix(last) + buildEventBody(last), earlier);
           if (!dispatched) {
             // Shutdown short-circuit — resolve un-acked so the server requeues
             // for the replacement pod and stop draining further items.
@@ -750,6 +763,8 @@ export class ParallAgentGateway {
             body: "[Orchestrator: fork session(s) completed — review results above]",
           };
           this.dispatchState.mainCurrentTargetId = undefined;
+          this.dispatchState.mainPreDispatchBranchPoint =
+            this.opts.dispatchAdapter.getBranchPoint?.(this.opts.runtimeKey);
           const dispatched = await this.runDispatch(syntheticEvent, this.opts.runtimeKey, forkPrefix + buildEventBody(syntheticEvent));
           if (!dispatched) {
             // Shutdown: put the fork results back at the head so the synthetic
@@ -772,8 +787,8 @@ export class ParallAgentGateway {
         const pendingFork = this.dispatchState.pendingForkResults.splice(0);
         const forkPrefix = buildForkResultPrefix(pendingFork);
         this.dispatchState.mainCurrentTargetId = event.targetId;
-        // Earlier-event input steps are persisted inside runDispatch (behind
-        // its shutdown gate) so a shutdown short-circuit cannot leave orphans.
+        this.dispatchState.mainPreDispatchBranchPoint =
+          this.opts.dispatchAdapter.getBranchPoint?.(this.opts.runtimeKey);
         const dispatched = await this.runDispatch(event, this.opts.runtimeKey, forkPrefix + buildEventBody(event), earlier);
         if (!dispatched) {
           // Shutdown: skip the ack so the server redelivers these buffered
@@ -796,6 +811,7 @@ export class ParallAgentGateway {
       this.draining = false;
       this.dispatchState.mainDispatching = false;
       this.dispatchState.mainCurrentTargetId = undefined;
+      this.dispatchState.mainPreDispatchBranchPoint = undefined;
     }
   }
 
@@ -808,6 +824,11 @@ export class ParallAgentGateway {
         const forkPrefix = buildForkResultPrefix(pendingFork);
         this.dispatchState.mainDispatching = true;
         this.dispatchState.mainCurrentTargetId = event.targetId;
+        // Snapshot the on-disk branch point BEFORE runDispatch starts writing
+        // to the session file. Fork sessions created while main is in-flight
+        // use this to branch from the clean pre-dispatch state.
+        this.dispatchState.mainPreDispatchBranchPoint =
+          this.opts.dispatchAdapter.getBranchPoint?.(this.opts.runtimeKey);
         let dispatched = false;
         try {
           dispatched = await this.runDispatch(event, this.opts.runtimeKey, forkPrefix + buildEventBody(event));
@@ -850,6 +871,7 @@ export class ParallAgentGateway {
         const fork = await this.opts.dispatchAdapter.forkSession({
           sessionKey: this.opts.runtimeKey,
           context: this.buildDispatchContext(event, this.opts.runtimeKey),
+          preDispatchBranchPoint: this.dispatchState.mainPreDispatchBranchPoint,
         });
 
         if (!fork) {
@@ -1188,6 +1210,53 @@ export class ParallAgentGateway {
     return dispatched;
   }
 
+  private async fetchAndHandleApprovalDecided(approvalId: string, actorId: string | null, chatId: string | null): Promise<boolean> {
+    let approval: Approval | null = null;
+    try {
+      approval = await this.opts.client.getApproval(approvalId);
+    } catch (err: unknown) {
+      const status = (err as { status?: number })?.status;
+      if (status === 404 || status === 403) {
+        this.opts.log?.warn(`parall[${this.opts.accountId}]: approval ${approvalId} not accessible (${status}), acking stale dispatch`);
+        return true;
+      }
+      this.opts.log?.warn(`parall[${this.opts.accountId}]: approval fetch failed for ${approvalId}, leaving pending: ${String(err)}`);
+      return false;
+    }
+    if (!approval) return true;
+
+    if (this.shuttingDown) return false;
+    const dedupeKey = `approval:${approval.id}`;
+    if (this.dispatchedTasks.has(dedupeKey)) return false;
+    this.dispatchedTasks.add(dedupeKey);
+    this.opts.log?.info(`parall[${this.opts.accountId}]: approval decided: ${approval.id} (${approval.status})`);
+
+    const statusLabel = approval.status === "approved" ? "Approved" : "Rejected";
+    const execInfo = approval.execution_status ? ` | execution: ${approval.execution_status}` : "";
+    const body = `${statusLabel}: ${approval.title}${execInfo}`;
+
+    const event: ParallEvent = {
+      type: "approval",
+      targetId: chatId ?? approval.chat_id,
+      senderId: actorId ?? approval.decided_by ?? "system",
+      senderName: "approver",
+      messageId: approval.id,
+      body,
+    };
+
+    let dispatched: boolean;
+    try {
+      dispatched = await this.handleInboundEvent(event);
+    } catch (err) {
+      this.dispatchedTasks.delete(dedupeKey);
+      throw err;
+    }
+    if (!dispatched) {
+      this.dispatchedTasks.delete(dedupeKey);
+    }
+    return dispatched;
+  }
+
   private async catchUpFromDispatch(coldStart = false) {
     const minAge = coldStart ? Date.now() - this.COLD_START_WINDOW_MS : 0;
     let cursor: string | undefined;
@@ -1231,6 +1300,8 @@ export class ParallAgentGateway {
             dispatched = await this.handleTaskComment(item.source_id, item.task_id, item.actor_id, item.delivery_reason);
           } else if (item.event_type === "schedule.fire" && item.source_id) {
             dispatched = await this.fetchAndHandleScheduleFire(item.source_id, item.actor_id);
+          } else if (item.event_type === "approval_decided" && item.source_id) {
+            dispatched = await this.fetchAndHandleApprovalDecided(item.source_id, item.actor_id, item.chat_id ?? null);
           } else if (item.event_type === "message" && item.source_id && item.chat_id) {
             if (!this.tryClaimMessage(item.source_id)) continue;
             let msg: Awaited<ReturnType<typeof this.opts.client.getMessage>> | null = null;

package/src/types.ts

@@ -12,11 +12,13 @@ export type DispatchState = {
   activeForks: Map<string, string>;
   pendingForkResults: ForkResult[];
   mainBuffer: ParallEvent[];
+  /** Snapshot of the session branch point taken BEFORE runDispatch starts on main. */
+  mainPreDispatchBranchPoint?: string;
 };
 
 /** Normalized inbound event from Parall. */
 export type ParallEvent = {
-  type: "message" | "task" | "task_comment" | "schedule";
+  type: "message" | "task" | "task_comment" | "schedule" | "approval";
   targetId: string;
   targetName?: string;
   targetType?: string;