@parall/agent-core 1.25.0 → 1.26.0

package/dist/bridge-workspace.d.ts

@@ -7,7 +7,7 @@
  * `@parall/agent-core` stays runtime-neutral and exports only text + pure
  * helpers here.
  */
-export declare const BRIDGE_WORKSPACE_INSTRUCTIONS = "# Agent workspace\n\nYou are an agent in Parall IM. You participate in chats, handle tasks, and interact exclusively through the Parall CLI.\n\n## Message Model\n\nIncoming events are rendered as structured `[Event: ...]` blocks.\nEach event includes `[Chat: ... (prll://cht_xxx)]` \u2014 use that chat ID (or full URI) when replying.\n\n**Your plain-text output is not delivered to anyone** \u2014 it is recorded as suppressed thinking in your session steps and discarded from the chat.\nTo say something in a chat, you **must** invoke the Parall CLI via your shell/exec tool. To stay silent, simply do not invoke it.\n\n## Parall CLI\n\nAll outbound interactions go through the `parall` CLI. Credentials are pre-injected as environment variables \u2014 no setup needed. If `parall` is not on PATH, use `npx --yes @parall/cli@latest` instead.\n\n- `parall messages send prll://cht_xxx --text \"...\"` \u2014 reply into the triggering chat\n- `parall dm prll://usr_xxx --text \"...\" [--no-reply]` \u2014 direct message another user\n- `parall tasks update prll://tsk_xxx --status in_progress` \u2014 task state\n- `parall no-reply [--reason \"...\"]` \u2014 explicitly declare this turn silent (audit signal; not required for silence, just clarifies intent)\n\nThe bridge injects Parall context via environment variables. The static credentials `PRLL_API_URL`, `PRLL_API_KEY`, and `PRLL_ORG_ID` are always set. Per-dispatch context \u2014 `PRLL_SESSION_ID`, `PRLL_CHAT_ID`, `PRLL_TRIGGER_MESSAGE_ID`, `PRLL_STEP_ID_FILE` \u2014 is set in subprocess-per-dispatch runtimes (Claude Code); in long-running runtimes (Codex) those may be absent and the CLI will fall back to whatever defaults you supply on the command line.\n\n## Attachments\n\nImage attachments are pre-downloaded under `.parall/attachments/<messageId>/`. Each event's `[Local attachment files]` block lists each image as a metadata header followed by its absolute local path on its own line \u2014 pass that path to your file-reading tool when the user refers to image contents.\n\nSupported image types: PNG, JPEG, WebP, GIF. Other attachment types (PDFs, archives, etc.) are not pre-downloaded \u2014 fetch them on demand with `parall files download att_xxx --output ...`.\n\n## Guardrails\n\n- A dispatch may coalesce multiple events. Decide per event whether to reply via `messages send` / `dm` \u2014 events you do not act on simply receive no reply.\n- If an event carries `[Hint: no_reply]`, do not send anything for that event. `no-reply` is optional and only useful as an explicit intent marker.\n- Never try to \"speak\" by typing sentences like \"No response needed\" / \"Noted\" / \"OK\" \u2014 they are discarded, so they accomplish nothing except polluting your session log.\n- Keep CLI replies concise and task-focused.\n\nSee `docs/engineering-design/agent-dm-loop-prevention.md` \u00A7 Layer 0 for why plain text is never auto-projected.\n\n## Approval Flow\n\nWhen you try an action (e.g., archive a chat) and receive a PERMISSION_DENIED error, you can request someone with permission to do it:\n\n1. The error includes a `PERMISSION_DENIED` code. For commonly approvable actions (archive, delete, restore), a `Tip:` line with an approval-request template is printed \u2014 copy it and fill in the remaining placeholders (`--chat`, `--title`, `--reason`)\n2. Request approval: `parall approvals request --action chat.archive --resource prll://cht_123 --chat prll://cht_456 --title \"Archive #old-project\" --reason \"Channel inactive\"`\n3. A card will appear in the specified chat for someone with permission to approve\n4. Check the result: `parall approvals get prll://<id>` or wait: `parall approvals wait prll://<id> --timeout 300`\n5. List available actions: `parall approvals actions`\n\nOnly request approval when you've actually been denied permission. Don't request approval preemptively.\n";
+export declare const BRIDGE_WORKSPACE_INSTRUCTIONS = "# Agent workspace\n\nYou are an agent in Parall IM. You participate in chats, handle tasks, and interact exclusively through the Parall CLI.\n\n## Message Model\n\nIncoming events are rendered as structured `[Event: ...]` blocks.\nEach event includes `[Chat: ... (prll://cht_xxx)]` \u2014 use that chat ID (or full URI) when replying.\n\n**Your plain-text output is not delivered to anyone** \u2014 it is recorded as suppressed thinking in your session steps and discarded from the chat.\nTo say something in a chat, you **must** invoke the Parall CLI via your shell/exec tool. To stay silent, simply do not invoke it.\n\n## Parall CLI\n\nAll outbound interactions go through the `parall` CLI. Credentials are pre-injected as environment variables \u2014 no setup needed. If `parall` is not on PATH, use `npx --yes @parall/cli@latest` instead.\n\n- `parall messages send prll://cht_xxx --text \"...\"` \u2014 reply into the triggering chat\n- `parall dm prll://usr_xxx --text \"...\" [--no-reply]` \u2014 direct message another user\n- `parall tasks update prll://tsk_xxx --status in_progress` \u2014 task state\n- `parall no-reply [--reason \"...\"]` \u2014 explicitly declare this turn silent (audit signal; not required for silence, just clarifies intent)\n\nThe bridge injects Parall context via environment variables. The static credentials `PRLL_API_URL`, `PRLL_API_KEY`, and `PRLL_ORG_ID` are always set. `PRLL_CONTEXT_FILE` points to a per-session JSON file that the gateway updates each dispatch with `session_id`, `chat_id`, `trigger_message_id`, `no_reply`, and `step_id` (updated per tool call). The CLI reads this file automatically \u2014 you do not need to pass `--chat` or `--session` explicitly when the context file is present.\n\n## Attachments\n\nImage attachments are pre-downloaded under `.parall/attachments/<messageId>/`. Each event's `[Local attachment files]` block lists each image as a metadata header followed by its absolute local path on its own line \u2014 pass that path to your file-reading tool when the user refers to image contents.\n\nSupported image types: PNG, JPEG, WebP, GIF. Other attachment types (PDFs, archives, etc.) are not pre-downloaded \u2014 fetch them on demand with `parall files download att_xxx --output ...`.\n\n## Guardrails\n\n- A dispatch may coalesce multiple events. Decide per event whether to reply via `messages send` / `dm` \u2014 events you do not act on simply receive no reply.\n- If an event carries `[Hint: no_reply]`, do not send anything for that event. `no-reply` is optional and only useful as an explicit intent marker.\n- Never try to \"speak\" by typing sentences like \"No response needed\" / \"Noted\" / \"OK\" \u2014 they are discarded, so they accomplish nothing except polluting your session log.\n- Keep CLI replies concise and task-focused.\n\nSee `docs/engineering-design/agent-dm-loop-prevention.md` \u00A7 Layer 0 for why plain text is never auto-projected.\n\n## Approval Flow\n\nWhen you try an action (e.g., archive a chat) and receive a PERMISSION_DENIED error, you can request someone with permission to do it:\n\n1. The error includes a `PERMISSION_DENIED` code. For commonly approvable actions (archive, delete, restore), a `Tip:` line with an approval-request template is printed \u2014 copy it and fill in the remaining placeholders (`--chat`, `--title`, `--reason`)\n2. Request approval: `parall approvals request --action chat.archive --resource prll://cht_123 --chat prll://cht_456 --title \"Archive #old-project\" --reason \"Channel inactive\"`\n3. A card will appear in the specified chat for someone with permission to approve\n4. Check the result: `parall approvals get prll://<id>` or wait: `parall approvals wait prll://<id> --timeout 300`\n5. List available actions: `parall approvals actions`\n\nOnly request approval when you've actually been denied permission. Don't request approval preemptively.\n";
 /** Extracts the `command` string from a shell/bash tool call's input payload. */
 export declare function extractShellCommand(input: unknown): string | undefined;
 /**

package/dist/bridge-workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-workspace.d.ts","sourceRoot":"","sources":["../src/bridge-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,6BAA6B,gzHAiDzC,CAAC;AAEF,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAItE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAmBzE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAKxE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAI3E"}
+{"version":3,"file":"bridge-workspace.d.ts","sourceRoot":"","sources":["../src/bridge-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,6BAA6B,00HAiDzC,CAAC;AAEF,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAItE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAmBzE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAKxE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAI3E"}

package/dist/bridge-workspace.js

@@ -28,7 +28,7 @@ All outbound interactions go through the \`parall\` CLI. Credentials are pre-inj
 - \`parall tasks update prll://tsk_xxx --status in_progress\` — task state
 - \`parall no-reply [--reason "..."]\` — explicitly declare this turn silent (audit signal; not required for silence, just clarifies intent)
 
-The bridge injects Parall context via environment variables. The static credentials \`PRLL_API_URL\`, \`PRLL_API_KEY\`, and \`PRLL_ORG_ID\` are always set. Per-dispatch context — \`PRLL_SESSION_ID\`, \`PRLL_CHAT_ID\`, \`PRLL_TRIGGER_MESSAGE_ID\`, \`PRLL_STEP_ID_FILE\` — is set in subprocess-per-dispatch runtimes (Claude Code); in long-running runtimes (Codex) those may be absent and the CLI will fall back to whatever defaults you supply on the command line.
+The bridge injects Parall context via environment variables. The static credentials \`PRLL_API_URL\`, \`PRLL_API_KEY\`, and \`PRLL_ORG_ID\` are always set. \`PRLL_CONTEXT_FILE\` points to a per-session JSON file that the gateway updates each dispatch with \`session_id\`, \`chat_id\`, \`trigger_message_id\`, \`no_reply\`, and \`step_id\` (updated per tool call). The CLI reads this file automatically — you do not need to pass \`--chat\` or \`--session\` explicitly when the context file is present.
 
 ## Attachments
 

package/dist/dispatch-adapter.d.ts

@@ -17,6 +17,8 @@ export type DispatchContext = {
     chatId?: string;
     triggerMessageId?: string;
     noReply: boolean;
+    contextFilePath?: string;
+    /** @deprecated Use contextFilePath. Kept for runtimes that haven't migrated. */
     stepIdFilePath?: string;
     client: ParallClient;
     log?: GatewayLogger;

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/gateway-base.d.ts

@@ -19,6 +19,8 @@ export type ParallGatewayOptions = {
     log?: GatewayLogger;
     coldStartWindowMs?: number;
     shutdownDeadlineMs?: number;
+    contextFilePathForSession?: (sessionKey: string) => string | undefined;
+    /** @deprecated Use contextFilePathForSession. Kept for runtimes that haven't migrated. */
     stepIdFilePathForSession?: (sessionKey: string) => string | undefined;
     onConfigUpdate?: (data: AgentConfigUpdateData) => Promise<void> | void;
     onSessionReady?: (state: {
@@ -57,7 +59,11 @@ export declare class ParallAgentGateway {
     private buildDispatchContext;
     private createInputStep;
     private createRuntimeStep;
+    private writeContextFile;
+    private updateContextFileStepId;
+    /** @deprecated Use writeContextFile / updateContextFileStepId. */
     private writeStepIdFile;
+    /** @deprecated Use writeContextFile / updateContextFileStepId. */
     private clearStepIdFile;
     private createInputStepsForEarlierEvents;
     private runDispatch;

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,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;YAmBd,eAAe;YA6Bf,iBAAiB;IAsF/B,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;YAQT,gCAAgC;YAUhC,WAAW;YAoFX,gBAAgB;YAkFhB,eAAe;YA6Ef,kBAAkB;YA2ElB,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

@@ -265,6 +265,7 @@ export class ParallAgentGateway {
             chatId: event.type === "message" ? event.targetId : undefined,
             triggerMessageId: event.messageId,
             noReply: event.noReply ?? false,
+            contextFilePath: this.opts.contextFilePathForSession?.(sessionKey),
             stepIdFilePath: this.opts.stepIdFilePathForSession?.(sessionKey),
             client: this.opts.client,
             log: this.opts.log,
@@ -298,7 +299,7 @@ export class ParallAgentGateway {
             this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to create input step: ${String(err)}`);
         }
     }
-    async createRuntimeStep(event, runtimeEvent, stepIdFilePath) {
+    async createRuntimeStep(event, runtimeEvent, stepIdFilePath, contextFilePath) {
         if (!this.activeSessionId)
             return;
         const target = resolveStepTarget(event);
@@ -341,7 +342,10 @@ export class ParallAgentGateway {
                         group_key: runtimeEvent.groupKey,
                         runtime_key: runtimeEvent.callId,
                     });
-                    if (stepIdFilePath) {
+                    if (contextFilePath) {
+                        this.updateContextFileStepId(contextFilePath, step.id);
+                    }
+                    else if (stepIdFilePath) {
                         this.writeStepIdFile(stepIdFilePath, step.id);
                     }
                     break;
@@ -361,7 +365,10 @@ export class ParallAgentGateway {
                         },
                         group_key: runtimeEvent.groupKey,
                     });
-                    if (stepIdFilePath) {
+                    if (contextFilePath) {
+                        this.updateContextFileStepId(contextFilePath, null);
+                    }
+                    else if (stepIdFilePath) {
                         this.clearStepIdFile(stepIdFilePath);
                     }
                     break;
@@ -380,6 +387,27 @@ export class ParallAgentGateway {
             this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to create ${runtimeEvent.type} step: ${String(err)}`);
         }
     }
+    writeContextFile(filePath, ctx) {
+        try {
+            fs.mkdirSync(path.dirname(filePath), { recursive: true });
+            fs.writeFileSync(filePath, JSON.stringify(ctx), "utf8");
+        }
+        catch (err) {
+            this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to write context file ${filePath}: ${String(err)}`);
+        }
+    }
+    updateContextFileStepId(filePath, stepId) {
+        try {
+            const raw = fs.readFileSync(filePath, "utf8");
+            const ctx = JSON.parse(raw);
+            ctx.step_id = stepId;
+            fs.writeFileSync(filePath, JSON.stringify(ctx), "utf8");
+        }
+        catch (err) {
+            this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to update context file step_id ${filePath}: ${String(err)}`);
+        }
+    }
+    /** @deprecated Use writeContextFile / updateContextFileStepId. */
     writeStepIdFile(filePath, stepId) {
         try {
             fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -389,6 +417,7 @@ export class ParallAgentGateway {
             this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to write step id file ${filePath}: ${String(err)}`);
         }
     }
+    /** @deprecated Use writeContextFile / updateContextFileStepId. */
     clearStepIdFile(filePath) {
         try {
             fs.writeFileSync(filePath, "", "utf8");
@@ -419,7 +448,17 @@ export class ParallAgentGateway {
         setDispatchMessageId(sessionKey, event.messageId);
         setDispatchNoReply(sessionKey, event.noReply ?? false);
         const dispatchContext = this.buildDispatchContext(event, sessionKey);
+        const contextFilePath = dispatchContext.contextFilePath;
         const stepIdFilePath = dispatchContext.stepIdFilePath;
+        if (contextFilePath) {
+            this.writeContextFile(contextFilePath, {
+                session_id: dispatchContext.sessionId ?? null,
+                chat_id: dispatchContext.chatId ?? null,
+                trigger_message_id: dispatchContext.triggerMessageId ?? null,
+                no_reply: dispatchContext.noReply,
+                step_id: null,
+            });
+        }
         // sync: no await between the shuttingDown check above and this increment
         // — JS event loop is single-threaded, so shutdown() cannot interleave
         // here and miss our in-flight count.
@@ -448,21 +487,24 @@ export class ParallAgentGateway {
                 sessionKey,
                 context: dispatchContext,
             })) {
-                await this.createRuntimeStep(event, runtimeEvent, stepIdFilePath);
+                await this.createRuntimeStep(event, runtimeEvent, stepIdFilePath, contextFilePath);
             }
         }
         catch (err) {
             await this.createRuntimeStep(event, {
                 type: "error",
                 message: `Dispatch failed: ${String(err)}`,
-            }, stepIdFilePath);
+            }, stepIdFilePath, contextFilePath);
             throw err;
         }
         finally {
             clearSessionMessageId(sessionKey);
             clearDispatchMessageId(sessionKey);
             clearDispatchNoReply(sessionKey);
-            if (stepIdFilePath) {
+            if (contextFilePath) {
+                this.updateContextFileStepId(contextFilePath, null);
+            }
+            else if (stepIdFilePath) {
                 this.clearStepIdFile(stepIdFilePath);
             }
             if (this.activeSessionId) {
@@ -661,9 +703,13 @@ export class ParallAgentGateway {
                 }
                 return dispatched;
             }
-            case "buffer-main":
+            case "buffer-main": {
+                if (this.shuttingDown) {
+                    return false;
+                }
                 this.dispatchState.mainBuffer.push(event);
                 return false;
+            }
             case "buffer-fork": {
                 const activeFork = this.forkStates.get(event.targetId);
                 if (!activeFork) {

package/dist/index.d.ts

@@ -6,4 +6,7 @@ export * from "./prompt-fragments.js";
 export * from "./bridge-workspace.js";
 export * from "./dispatch-adapter.js";
 export * from "./gateway-base.js";
+export * from "./platform-config.js";
+export { writeSkillFiles, buildSkillReferences, SKILLS } from "./skills/index.js";
+export type { SkillMeta } from "./skills/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAClF,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -6,3 +6,5 @@ export * from "./prompt-fragments.js";
 export * from "./bridge-workspace.js";
 export * from "./dispatch-adapter.js";
 export * from "./gateway-base.js";
+export * from "./platform-config.js";
+export { writeSkillFiles, buildSkillReferences, SKILLS } from "./skills/index.js";

package/dist/platform-config.d.ts

@@ -0,0 +1,23 @@
+import type { ParallClient } from "@parall/sdk";
+import type { GatewayLogger } from "./dispatch-adapter.js";
+export interface PlatformDefaults {
+    model: string | null;
+    thinkingEffort: string | null;
+}
+export interface PlatformConfigManager {
+    fetch(): Promise<PlatformDefaults>;
+    current(): PlatformDefaults;
+    rawConfig(): Record<string, unknown> | null;
+}
+export interface PlatformManagementProfile {
+    machine_id?: string | null;
+    model_management?: string | null;
+}
+export declare function isPlatformManagedProfile(profile: PlatformManagementProfile | null | undefined): boolean;
+export declare function createPlatformConfigManager(opts: {
+    client: ParallClient;
+    stateDir: string;
+    runtimeType?: string;
+    log?: GatewayLogger;
+}): PlatformConfigManager;
+//# sourceMappingURL=platform-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"platform-config.d.ts","sourceRoot":"","sources":["../src/platform-config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAA0B,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnC,OAAO,IAAI,gBAAgB,CAAC;IAC5B,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEvG;AA8ED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB,GAAG,qBAAqB,CAoDxB"}

package/dist/platform-config.js

@@ -0,0 +1,105 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export function isPlatformManagedProfile(profile) {
+    return profile?.machine_id != null || profile?.model_management === "platform";
+}
+const CACHE_FILENAME = "parall-platform-config.json";
+const SUPPORTED_SCHEMA_VERSION = 1;
+function cachePath(stateDir) {
+    return path.join(stateDir, CACHE_FILENAME);
+}
+function loadCache(stateDir) {
+    try {
+        const raw = fs.readFileSync(cachePath(stateDir), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function saveCache(stateDir, response) {
+    const cached = {
+        version: response.version,
+        config: response.config,
+        fetchedAt: new Date().toISOString(),
+    };
+    const filePath = cachePath(stateDir);
+    const tmpPath = `${filePath}.tmp`;
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(tmpPath, JSON.stringify(cached, null, 2), "utf-8");
+    fs.renameSync(tmpPath, filePath);
+}
+function runtimeModelName(canonicalModel, runtimeType, config) {
+    const runtime = runtimeType?.trim();
+    if (!runtime || runtime === "openclaw")
+        return canonicalModel;
+    const models = (config.models ?? {});
+    const providers = (models.providers ?? {});
+    const parall = (providers.parall ?? {});
+    const catalog = Array.isArray(parall.models) ? parall.models : [];
+    const match = catalog.find((model) => model.id === canonicalModel);
+    const runtimeNames = (match?.runtime_names ?? {});
+    const runtimeName = runtimeNames[runtime];
+    return typeof runtimeName === "string" && runtimeName ? runtimeName : null;
+}
+function extractDefaults(config, runtimeType) {
+    const agents = (config.agents ?? {});
+    const defaults = (agents.defaults ?? {});
+    let model = null;
+    if (typeof defaults.model === "string" && defaults.model) {
+        const canonicalModel = defaults.model.replace(/^parall\//, "");
+        model = runtimeModelName(canonicalModel, runtimeType, config);
+    }
+    let thinkingEffort = null;
+    if (typeof defaults.thinking_effort === "string" && defaults.thinking_effort) {
+        thinkingEffort = defaults.thinking_effort;
+    }
+    return { model, thinkingEffort };
+}
+export function createPlatformConfigManager(opts) {
+    const { client, stateDir, runtimeType, log } = opts;
+    let cachedVersion;
+    let currentDefaults = { model: null, thinkingEffort: null };
+    let currentRawConfig = null;
+    const cached = loadCache(stateDir);
+    if (cached) {
+        cachedVersion = cached.version;
+        currentRawConfig = cached.config;
+        currentDefaults = extractDefaults(cached.config, runtimeType);
+    }
+    return {
+        async fetch() {
+            let fresh = null;
+            try {
+                fresh = await client.getPlatformConfig(cachedVersion);
+            }
+            catch (err) {
+                if (cached) {
+                    log?.warn(`platform config fetch failed, using cached version ${cachedVersion}: ${String(err)}`);
+                    return currentDefaults;
+                }
+                log?.warn(`platform config fetch failed and no cache available: ${String(err)}`);
+                return currentDefaults;
+            }
+            if (fresh === null) {
+                return currentDefaults;
+            }
+            if (fresh.schema_version !== undefined && fresh.schema_version > SUPPORTED_SCHEMA_VERSION) {
+                log?.warn(`platform config schema_version ${fresh.schema_version} > supported (${SUPPORTED_SCHEMA_VERSION}), keeping current`);
+                return currentDefaults;
+            }
+            log?.info(`platform config updated to version ${fresh.version}`);
+            saveCache(stateDir, fresh);
+            cachedVersion = fresh.version;
+            currentRawConfig = fresh.config;
+            currentDefaults = extractDefaults(fresh.config, runtimeType);
+            return currentDefaults;
+        },
+        current() {
+            return currentDefaults;
+        },
+        rawConfig() {
+            return currentRawConfig;
+        },
+    };
+}

package/dist/skills/index.d.ts

@@ -0,0 +1,14 @@
+export { PARALL_PLATFORM_SKILL } from "./parall-platform.js";
+export { PARALL_TASKS_SKILL } from "./parall-tasks.js";
+export { PARALL_WIKI_SKILL } from "./parall-wiki.js";
+export { PARALL_SCHEDULES_SKILL } from "./parall-schedules.js";
+export type SkillMeta = {
+    name: string;
+    description: string;
+    content: string;
+};
+export declare const SKILLS: SkillMeta[];
+/** Write plain skill markdown files to a target directory (CC/Codex). */
+export declare function writeSkillFiles(targetDir: string): void;
+export declare function buildSkillReferences(workspaceDir: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/skills/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAO/D,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E,eAAO,MAAM,MAAM,EAAE,SAAS,EAqB7B,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAKvD;AAGD,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAIjE"}

package/dist/skills/index.js

@@ -0,0 +1,44 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export { PARALL_PLATFORM_SKILL } from "./parall-platform.js";
+export { PARALL_TASKS_SKILL } from "./parall-tasks.js";
+export { PARALL_WIKI_SKILL } from "./parall-wiki.js";
+export { PARALL_SCHEDULES_SKILL } from "./parall-schedules.js";
+import { PARALL_PLATFORM_SKILL } from "./parall-platform.js";
+import { PARALL_TASKS_SKILL } from "./parall-tasks.js";
+import { PARALL_WIKI_SKILL } from "./parall-wiki.js";
+import { PARALL_SCHEDULES_SKILL } from "./parall-schedules.js";
+export const SKILLS = [
+    {
+        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.",
+        content: PARALL_PLATFORM_SKILL,
+    },
+    {
+        name: "parall-tasks",
+        description: "Parall task operations: create, update, comment on, and query tasks and projects. Use when: user asks to create a task, update task status, add comments, list tasks, or manage projects.",
+        content: PARALL_TASKS_SKILL,
+    },
+    {
+        name: "parall-wiki",
+        description: "Parall wiki operations: read, search, edit, and propose changes to organization knowledge bases. Use when: user asks to read/write docs, edit wiki pages, search knowledge base, propose changes, or review changesets.",
+        content: PARALL_WIKI_SKILL,
+    },
+    {
+        name: "parall-schedules",
+        description: "Parall schedule operations: create / pause / resume / cancel recurring or one-shot time triggers; respond to schedule fire events. Use when: user asks to set up a recurring reminder, schedule a delayed prompt, run cron-like work, or when the agent receives an `[Event: schedule.fired]` dispatch.",
+        content: PARALL_SCHEDULES_SKILL,
+    },
+];
+/** Write plain skill markdown files to a target directory (CC/Codex). */
+export function writeSkillFiles(targetDir) {
+    fs.mkdirSync(targetDir, { recursive: true });
+    for (const skill of SKILLS) {
+        fs.writeFileSync(path.join(targetDir, `${skill.name}.md`), skill.content, "utf8");
+    }
+}
+export function buildSkillReferences(workspaceDir) {
+    const dir = path.join(workspaceDir, ".parall", "skills");
+    const lines = SKILLS.map((s) => `- ${s.description.split(":")[0]}: \`${dir}/${s.name}.md\``);
+    return `## Platform Skills (read on demand)\n\n${lines.join("\n")}\n`;
+}

package/dist/skills/parall-platform.d.ts

@@ -0,0 +1,2 @@
+export declare const PARALL_PLATFORM_SKILL = "# Parall Platform\n\nQuery organization data via the Parall CLI. Auth is pre-configured.\n\n## Identity\n\n```bash\nparall whoami\n```\n\n## Members & Agents\n\n```bash\nparall members list          # All org members (humans + agents)\nparall agents list           # Agents only\nparall users get prll://usr_xxx     # Get user details by ID\n```\n\nCreate a hosted agent when the user asks for a Parall-managed runtime. Hosted\nprovisioning is asynchronous: creation means the agent identity, API key, and\nmachine record were accepted, not that the runtime is online yet. Use `--wait`\nto wait until the machine reaches `running`, and use `--wait-online` when the\ntask requires the child agent to be connected before you report completion.\nFor hosted agents, use `--discard-api-key`; the server injects the one-time key\ninto the hosted runtime, so the parent agent must not print or persist it.\n\nCreate a self-hosted agent only when the runtime will be connected outside\nParall-managed compute. In that case, write the one-time `api_key` to\n`--api-key-file` so it is not captured in tool-result logs. Treat `api_key` as a\nsecret: do not print, read aloud, post it in shared chats, or echo the file\ncontents. Include the `user.id` in normal responses, and pass the key file only\nthrough an explicit secure runtime handoff when connection is required. Never\nuse `--show-api-key` from an agent runtime. Agent callers cannot set provider\noverrides until the dedicated fine-grained permission flow lands.\n\n```bash\n# Hosted runtime (Parall-managed compute)\nparall agents create \\\n  --name \"Research Agent\" \\\n  --runtime-type codex \\\n  --machine-type cloud \\\n  --machine-label standard \\\n  --discard-api-key \\\n  --wait \\\n  --wait-online\n\n# Self-hosted runtime\nparall agents create --name \"Research Agent\" --runtime-type codex --api-key-file /tmp/research-agent.api-key\n```\n\nInspect hosted provisioning directly when a create command returns before the\nruntime is online, or when you need logs for a failed machine. If `agents create`\nexits non-zero after creating a hosted agent, read the printed `user.id` and\n`machine.id`, then use these commands to decide whether to wait, inspect logs,\nor report the failed machine for retry.\n\n```bash\nparall machines status prll://mch_xxx\nparall machines logs prll://mch_xxx --lines 100\n```\n\n## Chats & Messages\n\n```bash\nparall chats list            # List all chats\nparall messages list prll://cht_xxx # Read chat message history\n```\n\n## Sending Messages\n\nEach `[Event: message.new]` includes `[Chat: ... (prll://cht_xxx)]` \u2014 use that chat URI to reply.\n\n```bash\n# Reply to a chat (use the chat URI from the event)\nparall messages send prll://cht_xxx --text \"Your reply\"\n\n# Direct message by user URI or display name\nparall dm prll://usr_xxx --text \"Hello\"\nparall dm \"Alice\" --text \"Hello\"\n\n# Thread reply\nparall messages send prll://cht_xxx --text \"Reply\" --thread-root-id 01JWC...\n\n# FYI message (no response expected \u2014 the recipient sees `[Hint: no_reply]`)\nparall messages send prll://cht_xxx --text \"FYI: done\" --no-reply\n\n# Silence this turn entirely \u2014 no chat message produced. Use when you receive\n# `[Hint: no_reply]` or otherwise decide the turn needs no visible reply.\n# Run BEFORE any `messages send` / `dm`; those still deliver real messages.\nparall no-reply --reason \"ack only, nothing to add\"\n```\n\n## Files & Attachments\n\nAttachments appear in events as `[Attachment: prll://att_xxx | mime | size | name]`.\n\n```bash\n# Download an attachment\nparall files download att_xxx --output /tmp/file.png\n\n# Upload a file (returns attachment_id)\nparall files upload /tmp/report.pdf\n\n# Send a message with a file\nparall messages send prll://cht_xxx --file /tmp/output.png --text \"Done\"\n\n# Send an existing attachment to another chat\nparall messages send prll://cht_xxx --attachment att_xxx --text \"See attached\"\n\n# DM with a file\nparall dm \"Alice\" --file /tmp/report.pdf --text \"Report attached\"\n```\n\n`--file` and `--attachment` are mutually exclusive. `--text` can be combined with either.\n\n## Approvals\n\nWhen a CLI command returns a `PERMISSION_DENIED` error, the output includes a `Tip:` line with an approval-request template \u2014 copy it and fill in the remaining placeholders (`--chat`, `--title`, `--reason`). The `Tip:` only appears for commonly approvable actions (archive, delete, restore); for other actions, use `parall approvals actions` to check if it's approvable.\n\n```bash\n# Request approval (use action and resource_uri from the error)\nparall approvals request --action chat.archive --resource prll://cht_xxx --chat prll://cht_yyy --title \"Archive old channel\" --reason \"No activity in 6 months\"\n\n# Check a specific approval's status\nparall approvals get prll://apr_xxx\n\n# Wait for a decision (blocks until approved/rejected/timeout)\nparall approvals wait prll://apr_xxx --timeout 300\n\n# List all your pending approvals\nparall approvals list\n\n# List available approvable actions\nparall approvals actions\n\n# Cancel a pending request you made\nparall approvals cancel prll://apr_xxx\n```\n\nOnly request approval after receiving an actual `PERMISSION_DENIED` error \u2014 never preemptively. The `--chat` flag specifies where the approval card appears; use the chat where the conversation is happening.\n\n## Reference URIs\n\nEvery entity is addressable with a `prll://` URI. Common prefixes you'll see in events, messages, and schedule descriptions:\n\n| Prefix | Entity | Skill |\n|--------|--------|-------|\n| `prll://usr_` | User (human or agent) | parall-platform |\n| `prll://cht_` | Chat | parall-platform |\n| `prll://msg_` | Message | parall-platform |\n| `prll://tsk_` | Task | parall-tasks |\n| `prll://prj_` | Project | parall-tasks |\n| `prll://sch_` | Schedule (time trigger) | parall-schedules |\n| `prll://srn_` | Schedule run (single fire audit record; carries fire-time snapshot) | parall-schedules |\n| `prll://wik_` | Wiki | parall-wiki |\n| `prll://att_` | Attachment | parall-platform (files) |\n\nWhen a message or event references `prll://sch_xxx` or `prll://srn_xxx`, or when you receive `[Event: schedule.fired]`, switch to the **parall-schedules** skill for the CLI commands (create / list / pause / resume / cancel / runs).\n\nAll CLI output is JSON.\n";
+//# sourceMappingURL=parall-platform.d.ts.map

package/dist/skills/parall-platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parall-platform.d.ts","sourceRoot":"","sources":["../../src/skills/parall-platform.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,swMAgKjC,CAAC"}

package/dist/skills/parall-platform.js

@@ -0,0 +1,161 @@
+export const PARALL_PLATFORM_SKILL = `# Parall Platform
+
+Query organization data via the Parall CLI. Auth is pre-configured.
+
+## Identity
+
+\`\`\`bash
+parall whoami
+\`\`\`
+
+## Members & Agents
+
+\`\`\`bash
+parall members list          # All org members (humans + agents)
+parall agents list           # Agents only
+parall users get prll://usr_xxx     # Get user details by ID
+\`\`\`
+
+Create a hosted agent when the user asks for a Parall-managed runtime. Hosted
+provisioning is asynchronous: creation means the agent identity, API key, and
+machine record were accepted, not that the runtime is online yet. Use \`--wait\`
+to wait until the machine reaches \`running\`, and use \`--wait-online\` when the
+task requires the child agent to be connected before you report completion.
+For hosted agents, use \`--discard-api-key\`; the server injects the one-time key
+into the hosted runtime, so the parent agent must not print or persist it.
+
+Create a self-hosted agent only when the runtime will be connected outside
+Parall-managed compute. In that case, write the one-time \`api_key\` to
+\`--api-key-file\` so it is not captured in tool-result logs. Treat \`api_key\` as a
+secret: do not print, read aloud, post it in shared chats, or echo the file
+contents. Include the \`user.id\` in normal responses, and pass the key file only
+through an explicit secure runtime handoff when connection is required. Never
+use \`--show-api-key\` from an agent runtime. Agent callers cannot set provider
+overrides until the dedicated fine-grained permission flow lands.
+
+\`\`\`bash
+# Hosted runtime (Parall-managed compute)
+parall agents create \\
+  --name "Research Agent" \\
+  --runtime-type codex \\
+  --machine-type cloud \\
+  --machine-label standard \\
+  --discard-api-key \\
+  --wait \\
+  --wait-online
+
+# Self-hosted runtime
+parall agents create --name "Research Agent" --runtime-type codex --api-key-file /tmp/research-agent.api-key
+\`\`\`
+
+Inspect hosted provisioning directly when a create command returns before the
+runtime is online, or when you need logs for a failed machine. If \`agents create\`
+exits non-zero after creating a hosted agent, read the printed \`user.id\` and
+\`machine.id\`, then use these commands to decide whether to wait, inspect logs,
+or report the failed machine for retry.
+
+\`\`\`bash
+parall machines status prll://mch_xxx
+parall machines logs prll://mch_xxx --lines 100
+\`\`\`
+
+## Chats & Messages
+
+\`\`\`bash
+parall chats list            # List all chats
+parall messages list prll://cht_xxx # Read chat message history
+\`\`\`
+
+## Sending Messages
+
+Each \`[Event: message.new]\` includes \`[Chat: ... (prll://cht_xxx)]\` — use that chat URI to reply.
+
+\`\`\`bash
+# Reply to a chat (use the chat URI from the event)
+parall messages send prll://cht_xxx --text "Your reply"
+
+# Direct message by user URI or display name
+parall dm prll://usr_xxx --text "Hello"
+parall dm "Alice" --text "Hello"
+
+# Thread reply
+parall messages send prll://cht_xxx --text "Reply" --thread-root-id 01JWC...
+
+# FYI message (no response expected — the recipient sees \`[Hint: no_reply]\`)
+parall messages send prll://cht_xxx --text "FYI: done" --no-reply
+
+# Silence this turn entirely — no chat message produced. Use when you receive
+# \`[Hint: no_reply]\` or otherwise decide the turn needs no visible reply.
+# Run BEFORE any \`messages send\` / \`dm\`; those still deliver real messages.
+parall no-reply --reason "ack only, nothing to add"
+\`\`\`
+
+## Files & Attachments
+
+Attachments appear in events as \`[Attachment: prll://att_xxx | mime | size | name]\`.
+
+\`\`\`bash
+# Download an attachment
+parall files download att_xxx --output /tmp/file.png
+
+# Upload a file (returns attachment_id)
+parall files upload /tmp/report.pdf
+
+# Send a message with a file
+parall messages send prll://cht_xxx --file /tmp/output.png --text "Done"
+
+# Send an existing attachment to another chat
+parall messages send prll://cht_xxx --attachment att_xxx --text "See attached"
+
+# DM with a file
+parall dm "Alice" --file /tmp/report.pdf --text "Report attached"
+\`\`\`
+
+\`--file\` and \`--attachment\` are mutually exclusive. \`--text\` can be combined with either.
+
+## Approvals
+
+When a CLI command returns a \`PERMISSION_DENIED\` error, the output includes a \`Tip:\` line with an approval-request template — copy it and fill in the remaining placeholders (\`--chat\`, \`--title\`, \`--reason\`). The \`Tip:\` only appears for commonly approvable actions (archive, delete, restore); for other actions, use \`parall approvals actions\` to check if it's approvable.
+
+\`\`\`bash
+# Request approval (use action and resource_uri from the error)
+parall approvals request --action chat.archive --resource prll://cht_xxx --chat prll://cht_yyy --title "Archive old channel" --reason "No activity in 6 months"
+
+# Check a specific approval's status
+parall approvals get prll://apr_xxx
+
+# Wait for a decision (blocks until approved/rejected/timeout)
+parall approvals wait prll://apr_xxx --timeout 300
+
+# List all your pending approvals
+parall approvals list
+
+# List available approvable actions
+parall approvals actions
+
+# Cancel a pending request you made
+parall approvals cancel prll://apr_xxx
+\`\`\`
+
+Only request approval after receiving an actual \`PERMISSION_DENIED\` error — never preemptively. The \`--chat\` flag specifies where the approval card appears; use the chat where the conversation is happening.
+
+## Reference URIs
+
+Every entity is addressable with a \`prll://\` URI. Common prefixes you'll see in events, messages, and schedule descriptions:
+
+| Prefix | Entity | Skill |
+|--------|--------|-------|
+| \`prll://usr_\` | User (human or agent) | parall-platform |
+| \`prll://cht_\` | Chat | parall-platform |
+| \`prll://msg_\` | Message | parall-platform |
+| \`prll://tsk_\` | Task | parall-tasks |
+| \`prll://prj_\` | Project | parall-tasks |
+| \`prll://sch_\` | Schedule (time trigger) | parall-schedules |
+| \`prll://srn_\` | Schedule run (single fire audit record; carries fire-time snapshot) | parall-schedules |
+| \`prll://wik_\` | Wiki | parall-wiki |
+| \`prll://att_\` | Attachment | parall-platform (files) |
+
+When a message or event references \`prll://sch_xxx\` or \`prll://srn_xxx\`, or when you receive \`[Event: schedule.fired]\`, switch to the **parall-schedules** skill for the CLI commands (create / list / pause / resume / cancel / runs).
+
+All CLI output is JSON.
+`;