@parall/agent-core 1.34.0 → 1.36.0

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;AAS1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA4FzD;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAEtE;AAyBD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAK/D;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAkBnE"}
+{"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;AAS1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAgHzD;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAEtE;AA6BD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAK/D;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAkBnE"}

package/dist/event-format.js

@@ -93,6 +93,28 @@ export function buildEventBody(event) {
             lines.push(`[Attached: ${sanitizeMeta(event.attachedUri)}]`);
         lines.push('', event.body);
     }
+    else if (event.type === 'external_trigger') {
+        lines.push(`[Event: external.trigger]`);
+        lines.push(`[Trigger: prll://${event.targetId}]`);
+        lines.push(`[Run: prll://${event.messageId}]`);
+        if (event.externalConnectionId) {
+            const label = event.externalConnectionDisplayName
+                ? `${sanitizeMeta(event.externalConnectionDisplayName)} (prll://${event.externalConnectionId})`
+                : `prll://${event.externalConnectionId}`;
+            lines.push(`[Connection: ${label}]`);
+        }
+        if (event.externalIngressEventId)
+            lines.push(`[Ingress: prll://${event.externalIngressEventId}]`);
+        if (event.attachedUri)
+            lines.push(`[Attached: ${sanitizeMeta(event.attachedUri)}]`);
+        if (event.externalConnectionSourceType) {
+            lines.push(`[Source: ${sanitizeMeta(event.externalConnectionSourceType)}]`);
+        }
+        if (event.externalIngressEventType) {
+            lines.push(`[External event: ${sanitizeMeta(event.externalIngressEventType)}]`);
+        }
+        lines.push('', event.body);
+    }
     else {
         lines.push(`[Event: task.assigned]`);
         const taskLabel = event.targetName
@@ -123,6 +145,9 @@ function buildSendMessageHint(event) {
     if (event.targetId.startsWith('sch_')) {
         return `\n<system-reminder>To communicate, use the CLI: \`parall messages send\` / \`parall dm\`. Your plain text output is not delivered.</system-reminder>`;
     }
+    if (event.type === 'external_trigger' || event.targetId.startsWith('xtr_')) {
+        return `\n<system-reminder>This external trigger is incoming-only. Your plain text output is not sent back to the external provider. To communicate in Parall, use \`parall messages send\` / \`parall dm\`; provider-specific outbound actions require a separate capability.</system-reminder>`;
+    }
     return '';
 }
 export function buildForkScopePrefix(event) {

package/dist/gateway-base.d.ts

@@ -104,6 +104,8 @@ export declare class ParallAgentGateway {
      */
     private fetchAndHandleScheduleFire;
     private handleScheduleFire;
+    private fetchAndHandleExternalTriggerRun;
+    private handleExternalTriggerRun;
     private fetchAndHandleApprovalDecided;
     private catchUpFromDispatch;
     private buildOfflineSummary;

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

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

package/dist/gateway-base.js

@@ -50,6 +50,9 @@ function resolveStepTarget(event) {
     if (event.type === 'schedule' || event.targetId.startsWith('sch_')) {
         return { target_type: 'schedule', target_id: event.targetId };
     }
+    if (event.type === 'external_trigger' || event.targetId.startsWith('xtr_')) {
+        return { target_type: 'external_trigger', target_id: event.targetId };
+    }
     if (event.type === 'wiki_comment') {
         // target_id is the full wiki target_uri (scheme-stripped routing key). The
         // server stores target_type freely and only publishes step WS events /
@@ -286,6 +289,19 @@ export class ParallAgentGateway {
                     this.opts.log?.error(`schedule fire dispatch failed for ${data.source_id}: ${String(err)}`);
                 }
             }
+            else if (data.event_type === 'external_trigger') {
+                if (!data.source_id)
+                    return;
+                try {
+                    const dispatched = await this.fetchAndHandleExternalTriggerRun(data.source_id);
+                    if (dispatched) {
+                        this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => { });
+                    }
+                }
+                catch (err) {
+                    this.opts.log?.error(`external trigger dispatch failed for ${data.source_id}: ${String(err)}`);
+                }
+            }
             else if (data.event_type === 'approval_decided') {
                 if (!data.source_id)
                     return;
@@ -382,9 +398,11 @@ export class ParallAgentGateway {
                                 ? 'wiki_comment'
                                 : event.type === 'schedule'
                                     ? 'schedule_fire'
-                                    : event.type === 'approval'
-                                        ? 'approval_decided'
-                                        : 'mention',
+                                    : event.type === 'external_trigger'
+                                        ? 'external_trigger'
+                                        : event.type === 'approval'
+                                            ? 'approval_decided'
+                                            : 'mention',
                     trigger_ref: event.type === 'task'
                         ? { task_id: event.targetId }
                         : event.type === 'task_comment'
@@ -393,9 +411,16 @@ export class ParallAgentGateway {
                                 ? { comment_id: event.messageId, target_uri: event.replyTargetUri }
                                 : event.type === 'schedule'
                                     ? { schedule_id: event.targetId, run_id: event.messageId }
-                                    : event.type === 'approval'
-                                        ? { approval_id: event.messageId }
-                                        : { message_id: event.messageId },
+                                    : event.type === 'external_trigger'
+                                        ? {
+                                            trigger_id: event.targetId,
+                                            run_id: event.messageId,
+                                            connection_id: event.externalConnectionId,
+                                            ingress_event_id: event.externalIngressEventId,
+                                        }
+                                        : 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),
@@ -1037,6 +1062,13 @@ export class ParallAgentGateway {
             this.dispatchState.mainCurrentTargetId = undefined;
             this.dispatchState.mainPreDispatchBranchPoint = undefined;
             if (!this.shuttingDown && this.dispatchState.mainBuffer.length > 0) {
+                // Opportunistic re-drain — best-effort, not a recovery deadline, so it
+                // must not be the sole handle keeping the event loop alive. In a live
+                // bridge the WS connection holds the loop open and this still fires;
+                // when nothing else is pending there is no runtime to drain to anyway,
+                // and an un-ref'd timer lets the process (or a test run) exit instead
+                // of idling out the 5s. The abort deadlines deliberately stay ref'd —
+                // firing as the sole handle IS their recovery job.
                 setTimeout(() => {
                     if (!this.draining &&
                         !this.dispatchState.mainDispatching &&
@@ -1044,7 +1076,7 @@ export class ParallAgentGateway {
                         this.dispatchState.mainDispatching = true;
                         void this.drainMainBuffer();
                     }
-                }, 5000);
+                }, 5000).unref();
             }
         }
     }
@@ -1562,6 +1594,66 @@ export class ParallAgentGateway {
         }
         return dispatched;
     }
+    async fetchAndHandleExternalTriggerRun(runId) {
+        let run = null;
+        try {
+            run = await this.opts.client.getExternalTriggerRun(this.opts.config.org_id, runId);
+        }
+        catch (err) {
+            const status = err?.status;
+            if (status === 404) {
+                this.opts.log?.warn(`external trigger run ${runId} not accessible (404), acking stale dispatch`);
+                return true;
+            }
+            this.opts.log?.warn(`external trigger run fetch failed for ${runId}, leaving pending: ${String(err)}`);
+            return false;
+        }
+        if (!run)
+            return true;
+        return this.handleExternalTriggerRun(run);
+    }
+    async handleExternalTriggerRun(run) {
+        if (this.shuttingDown)
+            return false;
+        const dedupeKey = `external_trigger_run:${run.id}`;
+        if (this.dispatchedTasks.has(dedupeKey))
+            return false;
+        this.dispatchedTasks.add(dedupeKey);
+        this.opts.log?.info(`external trigger fired: ${run.id} (trigger ${run.trigger_id})`);
+        const attachedUri = typeof run.trigger_snapshot?.attached_to_uri === 'string'
+            ? run.trigger_snapshot.attached_to_uri
+            : undefined;
+        const event = {
+            type: 'external_trigger',
+            targetId: run.trigger_id,
+            targetName: run.trigger_name || undefined,
+            targetType: 'external_trigger',
+            senderId: 'system',
+            senderName: 'external',
+            messageId: run.id,
+            body: run.agent_input_body ?? '',
+            externalConnectionId: run.connection_id,
+            externalConnectionSourceType: run.connection_source_type || undefined,
+            externalConnectionDisplayName: run.connection_display_name || undefined,
+            externalIngressEventId: run.ingress_event_id,
+            externalIngressEventType: run.ingress_event_type || undefined,
+            attachedUri,
+            ackSourceType: 'external_trigger_run',
+            ackSourceId: run.id,
+        };
+        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 fetchAndHandleApprovalDecided(approvalId, actorId, chatId) {
         let approval = null;
         try {
@@ -1685,6 +1777,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 === 'external_trigger' && item.source_id) {
+                        dispatched = await this.fetchAndHandleExternalTriggerRun(item.source_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);
                     }

package/dist/skills/index.d.ts

@@ -2,6 +2,7 @@ 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 { PARALL_EXTERNAL_TRIGGERS_SKILL } from './parall-external-triggers.js';
 export { PARALL_CLIPS_SKILL } from './parall-clips.js';
 export type SkillMeta = {
     name: string;

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

@@ -1 +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;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAQvD,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,EA+B7B,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAKvD;AAED,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAIjE"}
+{"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;AAC/D,OAAO,EAAE,8BAA8B,EAAE,MAAM,+BAA+B,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AASvD,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,EAqC7B,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAKvD;AAED,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAIjE"}

package/dist/skills/index.js

@@ -4,11 +4,13 @@ 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 { PARALL_EXTERNAL_TRIGGERS_SKILL } from './parall-external-triggers.js';
 export { PARALL_CLIPS_SKILL } from './parall-clips.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';
+import { PARALL_EXTERNAL_TRIGGERS_SKILL } from './parall-external-triggers.js';
 import { PARALL_CLIPS_SKILL } from './parall-clips.js';
 export const SKILLS = [
     {
@@ -31,6 +33,11 @@ export const SKILLS = [
         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,
     },
+    {
+        name: 'parall-external-triggers',
+        description: 'Parall External Trigger operations: create incoming connections, configure CEL/Liquid triggers, inspect incoming events and runs, and respond to `[Event: external.trigger]` dispatches. Use when: user asks to connect an external system to an agent, set up incoming callbacks/notifications, or when the agent receives an external trigger event.',
+        content: PARALL_EXTERNAL_TRIGGERS_SKILL,
+    },
     {
         name: 'parall-clips',
         description: 'Parall clip operations: list installed clips, invoke clip commands, inspect clip details. Use when: the task requires external capabilities (GitHub, web search, etc.), user asks about available tools/clips, or you need to call a clip command.',

package/dist/skills/parall-external-triggers.d.ts

@@ -0,0 +1,2 @@
+export declare const PARALL_EXTERNAL_TRIGGERS_SKILL = "# Parall External Triggers\n\nAn **External Trigger** is an incoming platform trigger. External systems send events to an External Trigger Connection, Parall matches active triggers with CEL, renders a Liquid template into an agent input body, and dispatches that input to the configured target agents.\n\nUse External Triggers for incoming events such as GitHub callbacks, Slack/Feishu notifications, generic webhooks, or emails once the platform has a connection for them. The runtime behavior is incoming-only: receiving a trigger does not imply that you can call the external system back unless another explicit Parall capability is available.\n\n## Prerequisite\n\nExternal Trigger CLI commands are gated by the org-level `external-triggers` feature flag. If a command reports that the feature is unavailable, ask a human org admin to enable the flag before trying again. Public ingress delivery may still be live even when the management CLI is hidden behind the rollout flag.\n\n## Creating a trigger\n\n```bash\n# 1. Create a connection. The ingress token is shown once; prefer writing it\n# to a local file so it does not land in shell history or logs.\nparall external-triggers create-connection --name \"GitHub CI\" --token-file ./github-ci-webhook-token.txt\n\n# 2. Create a trigger that targets one or more agents.\nparall external-triggers create \\\n  --connection prll://xcn_xxx \\\n  --name \"Failed checks\" \\\n  --target-ids prll://usr_agent_xxx \\\n  --filter \"body.json.check_run.conclusion == 'failure'\" \\\n  --template-file ./github-check-failed.md \\\n  --attached-to-uri prll://tsk_xxx\n```\n\n`--filter` is CEL. Omit it to match all incoming events (`true`). Keep filters small and deterministic; do not model provider-specific branching in agent code when the CEL expression can select the relevant events first.\n\n`--template` / `--template-file` is Liquid with the safe Parall profile. It can read event data, body data, safe request metadata, trigger fields, run fields, and connection fields. It cannot call HTTP, read databases, evaluate arbitrary code, access platform secrets, or read arbitrary request headers/query parameters.\n\nExample template:\n\n```liquid\nGitHub check failed.\n\nEvent: {{ request.headers.x_github_event | default: \"unknown\" }}\nRepo: {{ body.json.repository.full_name }}\nPR: {{ body.json.pull_request.number }} {{ body.json.pull_request.title }}\nCheck: {{ body.json.check_run.name }}\nConclusion: {{ body.json.check_run.conclusion }}\n\nRun: {{ body.json.check_run.html_url }}\n```\n\nDo not render access tokens, signing secrets, cookies, or private credentials into agent input. Request snapshots and bodies may contain third-party data; treat them as user-provided input.\n\n## Inspecting and lifecycle\n\n```bash\nparall external-triggers connections\nparall external-triggers connection prll://xcn_xxx\nparall external-triggers schema prll://xcn_xxx\n\nparall external-triggers list\nparall external-triggers list --connection prll://xcn_xxx\nparall external-triggers get prll://xtr_xxx\nparall external-triggers update prll://xtr_xxx --filter \"event.type == 'check_run'\"\nparall external-triggers pause prll://xtr_xxx\nparall external-triggers resume prll://xtr_xxx\nparall external-triggers delete prll://xtr_xxx\n\nparall external-triggers runs prll://xtr_xxx\nparall external-triggers run prll://xrn_xxx\nparall external-triggers events --connection prll://xcn_xxx\nparall external-triggers event prll://xin_xxx\n```\n\n## Responding to external trigger dispatches\n\nWhen you receive `[Event: external.trigger]`, Parall has already matched a trigger and rendered its template. The prompt includes headers such as:\n\n- `[Trigger: prll://xtr_xxx]`\n- `[Run: prll://xrn_xxx]`\n- `[Connection: ... (prll://xcn_xxx)]`\n- `[Ingress: prll://xin_xxx]`\n- Optional `[Attached: prll://...]`\n\nThe rendered agent input body follows those headers. You usually do not need to fetch the run before acting. Fetch the run only for audit/debugging:\n\n```bash\nparall external-triggers run prll://xrn_xxx\n```\n\nAct on the rendered input the same way you would act on a user message: send a message, create or update tasks, edit wiki pages, or use available clips. If no visible response is needed, use `parall no-reply --reason \"handled external trigger\"` before sending any message.\n\nCLI command results are JSON on stdout; mutation commands may emit auxiliary hints on stderr, for example `Created: prll://xtr_xxx`.\n";
+//# sourceMappingURL=parall-external-triggers.d.ts.map

package/dist/skills/parall-external-triggers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parall-external-triggers.d.ts","sourceRoot":"","sources":["../../src/skills/parall-external-triggers.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,8BAA8B,g5IAuF1C,CAAC"}

package/dist/skills/parall-external-triggers.js

@@ -0,0 +1,88 @@
+export const PARALL_EXTERNAL_TRIGGERS_SKILL = `# Parall External Triggers
+
+An **External Trigger** is an incoming platform trigger. External systems send events to an External Trigger Connection, Parall matches active triggers with CEL, renders a Liquid template into an agent input body, and dispatches that input to the configured target agents.
+
+Use External Triggers for incoming events such as GitHub callbacks, Slack/Feishu notifications, generic webhooks, or emails once the platform has a connection for them. The runtime behavior is incoming-only: receiving a trigger does not imply that you can call the external system back unless another explicit Parall capability is available.
+
+## Prerequisite
+
+External Trigger CLI commands are gated by the org-level \`external-triggers\` feature flag. If a command reports that the feature is unavailable, ask a human org admin to enable the flag before trying again. Public ingress delivery may still be live even when the management CLI is hidden behind the rollout flag.
+
+## Creating a trigger
+
+\`\`\`bash
+# 1. Create a connection. The ingress token is shown once; prefer writing it
+# to a local file so it does not land in shell history or logs.
+parall external-triggers create-connection --name "GitHub CI" --token-file ./github-ci-webhook-token.txt
+
+# 2. Create a trigger that targets one or more agents.
+parall external-triggers create \\
+  --connection prll://xcn_xxx \\
+  --name "Failed checks" \\
+  --target-ids prll://usr_agent_xxx \\
+  --filter "body.json.check_run.conclusion == 'failure'" \\
+  --template-file ./github-check-failed.md \\
+  --attached-to-uri prll://tsk_xxx
+\`\`\`
+
+\`--filter\` is CEL. Omit it to match all incoming events (\`true\`). Keep filters small and deterministic; do not model provider-specific branching in agent code when the CEL expression can select the relevant events first.
+
+\`--template\` / \`--template-file\` is Liquid with the safe Parall profile. It can read event data, body data, safe request metadata, trigger fields, run fields, and connection fields. It cannot call HTTP, read databases, evaluate arbitrary code, access platform secrets, or read arbitrary request headers/query parameters.
+
+Example template:
+
+\`\`\`liquid
+GitHub check failed.
+
+Event: {{ request.headers.x_github_event | default: "unknown" }}
+Repo: {{ body.json.repository.full_name }}
+PR: {{ body.json.pull_request.number }} {{ body.json.pull_request.title }}
+Check: {{ body.json.check_run.name }}
+Conclusion: {{ body.json.check_run.conclusion }}
+
+Run: {{ body.json.check_run.html_url }}
+\`\`\`
+
+Do not render access tokens, signing secrets, cookies, or private credentials into agent input. Request snapshots and bodies may contain third-party data; treat them as user-provided input.
+
+## Inspecting and lifecycle
+
+\`\`\`bash
+parall external-triggers connections
+parall external-triggers connection prll://xcn_xxx
+parall external-triggers schema prll://xcn_xxx
+
+parall external-triggers list
+parall external-triggers list --connection prll://xcn_xxx
+parall external-triggers get prll://xtr_xxx
+parall external-triggers update prll://xtr_xxx --filter "event.type == 'check_run'"
+parall external-triggers pause prll://xtr_xxx
+parall external-triggers resume prll://xtr_xxx
+parall external-triggers delete prll://xtr_xxx
+
+parall external-triggers runs prll://xtr_xxx
+parall external-triggers run prll://xrn_xxx
+parall external-triggers events --connection prll://xcn_xxx
+parall external-triggers event prll://xin_xxx
+\`\`\`
+
+## Responding to external trigger dispatches
+
+When you receive \`[Event: external.trigger]\`, Parall has already matched a trigger and rendered its template. The prompt includes headers such as:
+
+- \`[Trigger: prll://xtr_xxx]\`
+- \`[Run: prll://xrn_xxx]\`
+- \`[Connection: ... (prll://xcn_xxx)]\`
+- \`[Ingress: prll://xin_xxx]\`
+- Optional \`[Attached: prll://...]\`
+
+The rendered agent input body follows those headers. You usually do not need to fetch the run before acting. Fetch the run only for audit/debugging:
+
+\`\`\`bash
+parall external-triggers run prll://xrn_xxx
+\`\`\`
+
+Act on the rendered input the same way you would act on a user message: send a message, create or update tasks, edit wiki pages, or use available clips. If no visible response is needed, use \`parall no-reply --reason "handled external trigger"\` before sending any message.
+
+CLI command results are JSON on stdout; mutation commands may emit auxiliary hints on stderr, for example \`Created: prll://xtr_xxx\`.
+`;

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

@@ -1,2 +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 the denied `action` and `resource_uri`. Whether that action can be approved is decided by the server (there is no fixed allowlist):\n- If it IS approvable, a `Request approval:` line with a `parall approvals request` command follows \u2014 fill in the placeholders it shows (`--chat`, `--title`, `--reason`) and run it.\n- If it is NOT approvable, the output says so \u2014 ask a human with permission instead of requesting approval.\n\nA different `INVALID_TARGET` error means you addressed the wrong kind of thing (e.g. a `usr_` id where a chat is expected). Follow the message (e.g. use `parall dm` to message a user) \u2014 do not request approval for it.\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\nCLI success output is JSON. Errors print a JSON line (`{\"error\",\"status\",\"code\",...}`) and, on a `PERMISSION_DENIED`, may add a plain-text `Request approval:` line \u2014 read both.\n";
+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 the denied `action` and `resource_uri`. Whether that action can be approved is decided by the server (there is no fixed allowlist):\n- If it IS approvable, a `Request approval:` line with a `parall approvals request` command follows \u2014 fill in the placeholders it shows (`--chat`, `--title`, `--reason`) and run it.\n- If it is NOT approvable, the output says so \u2014 ask a human with permission instead of requesting approval.\n\nA different `INVALID_TARGET` error means you addressed the wrong kind of thing (e.g. a `usr_` id where a chat is expected). Follow the message (e.g. use `parall dm` to message a user) \u2014 do not request approval for it.\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://xcn_` | External Trigger Connection (incoming endpoint) | parall-external-triggers |\n| `prll://xin_` | External Trigger Event (single incoming event audit record) | parall-external-triggers |\n| `prll://xtr_` | External Trigger (incoming trigger configuration) | parall-external-triggers |\n| `prll://xrn_` | External Trigger run (single matched dispatch audit record) | parall-external-triggers |\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\nWhen a message or event references `prll://xcn_xxx`, `prll://xin_xxx`, `prll://xtr_xxx`, or `prll://xrn_xxx`, or when you receive `[Event: external.trigger]`, switch to the **parall-external-triggers** skill for the CLI commands (connections / triggers / events / runs).\n\nCLI success output is JSON. Errors print a JSON line (`{\"error\",\"status\",\"code\",...}`) and, on a `PERMISSION_DENIED`, may add a plain-text `Request approval:` line \u2014 read both.\n";
 //# sourceMappingURL=parall-platform.d.ts.map

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

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

package/dist/skills/parall-platform.js

@@ -156,10 +156,16 @@ Every entity is addressable with a \`prll://\` URI. Common prefixes you'll see i
 | \`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://xcn_\` | External Trigger Connection (incoming endpoint) | parall-external-triggers |
+| \`prll://xin_\` | External Trigger Event (single incoming event audit record) | parall-external-triggers |
+| \`prll://xtr_\` | External Trigger (incoming trigger configuration) | parall-external-triggers |
+| \`prll://xrn_\` | External Trigger run (single matched dispatch audit record) | parall-external-triggers |
 | \`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).
 
+When a message or event references \`prll://xcn_xxx\`, \`prll://xin_xxx\`, \`prll://xtr_xxx\`, or \`prll://xrn_xxx\`, or when you receive \`[Event: external.trigger]\`, switch to the **parall-external-triggers** skill for the CLI commands (connections / triggers / events / runs).
+
 CLI success output is JSON. Errors print a JSON line (\`{"error","status","code",...}\`) and, on a \`PERMISSION_DENIED\`, may add a plain-text \`Request approval:\` line — read both.
 `;

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

@@ -1,2 +1,2 @@
-export declare const PARALL_TASKS_SKILL = "# Parall Tasks\n\nManage tasks and projects via the Parall CLI. Auth and runtime context are pre-configured.\n\n## Task Commands\n\n```bash\n# List tasks (filterable by status)\nparall tasks list\nparall tasks list --status todo\nparall tasks list --status in_progress\n\n# Create a task\nparall tasks create --title \"Task title\" [--assignee-id prll://usr_xxx] [--project-id prll://prj_xxx]\n\n# Update task status\nparall tasks update prll://tsk_xxx --status in_progress\nparall tasks update prll://tsk_xxx --status done\n\n# Add a comment\nparall tasks comments add prll://tsk_xxx --body \"Progress update...\"\n```\n\n## Project Commands\n\n```bash\nparall projects list\n```\n\n## Watching Tasks\n\nSubscribe to a task to receive notifications when others comment on it.\n\n```bash\n# Watch a task (you'll receive dispatch events for new comments)\nparall tasks watch prll://tsk_xxx\n\n# Unwatch\nparall tasks unwatch prll://tsk_xxx\n\n# List who is watching\nparall tasks watchers prll://tsk_xxx\n```\n\nNote: task creators are automatically watching their tasks.\n\n## Responding to Task Assignments\n\nWhen you receive `[Event: task.assigned]`:\n\n1. Acknowledge with a comment: `tasks comments add prll://tsk_xxx --body \"On it\"`\n2. Update status: `tasks update prll://tsk_xxx --status in_progress`\n3. Do the work\n4. Report results via comment and update status to `done`\n\n## Responding to Task Comments\n\nWhen you receive `[Event: task.comment.created]`, someone commented on a task you are watching. Read the comment body and respond if action is needed:\n\n1. Review the comment content and task context\n2. Reply via comment: `tasks comments add prll://tsk_xxx --body \"Response...\"`\n3. If the comment requests status changes, update accordingly\n\nCLI success output is JSON; errors print a JSON line plus, on a `PERMISSION_DENIED`, an optional plain-text `Request approval:` line \u2014 read both.\n";
+export declare const PARALL_TASKS_SKILL = "# Parall Tasks\n\nManage tasks and projects via the Parall CLI. Auth and runtime context are pre-configured.\n\n## Finding What's on Someone's Plate (incl. subtasks)\n\nTo answer \"what do I still have to do\", \"what's <person> working on\", or any\n\"open work assigned to X\" question, use `tasks assigned`:\n\n```bash\n# Pending tasks (todo + in_progress) assigned to a member \u2014 INCLUDES subtasks.\nparall tasks assigned prll://usr_xxx   # a specific person (e.g. the human who asked)\nparall tasks assigned                  # yourself (defaults to the authenticated user)\n```\n\nThis is the authoritative \"open work for a person\" query. It returns every\npending task assigned to that member **including subtasks** \u2014 even when the\nsubtask's parent task belongs to someone else. Decomposed work usually lives in\nsubtasks, so do NOT answer this kind of question from `tasks list` alone:\nthat is org-wide, page-capped, and not scoped to a person, so a person's\nsubtasks are easily missed.\n\nResolve a person's `prll://usr_` id from the message context, the members\nlist, or ref search; your own id comes from `parall whoami`.\n\n## Task Commands\n\n```bash\n# List tasks (org-wide; filter by status, assignee, or parent)\nparall tasks list\nparall tasks list --status todo\nparall tasks list --status in_progress\nparall tasks list --assignee-id prll://usr_xxx   # first page only (default 20) \u2014 for a person's FULL backlog use 'tasks assigned' above\nparall tasks subtasks prll://tsk_xxx             # children of a single parent task\n\n# Create a task (add --parent-id to make it a SUBTASK of another task)\nparall tasks create --title \"Task title\" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx]\n\n# Update task status\nparall tasks update prll://tsk_xxx --status in_progress\nparall tasks update prll://tsk_xxx --status done\n\n# Add a comment\nparall tasks comments add prll://tsk_xxx --body \"Progress update...\"\n```\n\nSubtasks are just tasks with a parent: create one with `tasks create --parent-id`,\nre-parent with `tasks update --parent-id`, list a parent's children with\n`tasks subtasks`. `tasks list` without `--parent-id` already returns both\ntop-level tasks and subtasks; per-person open work is best fetched with\n`tasks assigned` (above).\n\n## Project Commands\n\n```bash\nparall projects list\n```\n\n## Watching Tasks\n\nSubscribe to a task to receive notifications when others comment on it.\n\n```bash\n# Watch a task (you'll receive dispatch events for new comments)\nparall tasks watch prll://tsk_xxx\n\n# Unwatch\nparall tasks unwatch prll://tsk_xxx\n\n# List who is watching\nparall tasks watchers prll://tsk_xxx\n```\n\nNote: task creators are automatically watching their tasks.\n\n## Responding to Task Assignments\n\nWhen you receive `[Event: task.assigned]`:\n\n1. Acknowledge with a comment: `tasks comments add prll://tsk_xxx --body \"On it\"`\n2. Update status: `tasks update prll://tsk_xxx --status in_progress`\n3. Do the work\n4. Report results via comment and update status to `done`\n\n## Responding to Task Comments\n\nWhen you receive `[Event: task.comment.created]`, someone commented on a task you are watching. Read the comment body and respond if action is needed:\n\n1. Review the comment content and task context\n2. Reply via comment: `tasks comments add prll://tsk_xxx --body \"Response...\"`\n3. If the comment requests status changes, update accordingly\n\nCLI success output is JSON; errors print a JSON line plus, on a `PERMISSION_DENIED`, an optional plain-text `Request approval:` line \u2014 read both.\n";
 //# sourceMappingURL=parall-tasks.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"parall-tasks.d.ts","sourceRoot":"","sources":["../../src/skills/parall-tasks.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,y4DAgE9B,CAAC"}
+{"version":3,"file":"parall-tasks.d.ts","sourceRoot":"","sources":["../../src/skills/parall-tasks.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,yjHA6F9B,CAAC"}

package/dist/skills/parall-tasks.js

@@ -2,16 +2,39 @@ export const PARALL_TASKS_SKILL = `# Parall Tasks
 
 Manage tasks and projects via the Parall CLI. Auth and runtime context are pre-configured.
 
+## Finding What's on Someone's Plate (incl. subtasks)
+
+To answer "what do I still have to do", "what's <person> working on", or any
+"open work assigned to X" question, use \`tasks assigned\`:
+
+\`\`\`bash
+# Pending tasks (todo + in_progress) assigned to a member — INCLUDES subtasks.
+parall tasks assigned prll://usr_xxx   # a specific person (e.g. the human who asked)
+parall tasks assigned                  # yourself (defaults to the authenticated user)
+\`\`\`
+
+This is the authoritative "open work for a person" query. It returns every
+pending task assigned to that member **including subtasks** — even when the
+subtask's parent task belongs to someone else. Decomposed work usually lives in
+subtasks, so do NOT answer this kind of question from \`tasks list\` alone:
+that is org-wide, page-capped, and not scoped to a person, so a person's
+subtasks are easily missed.
+
+Resolve a person's \`prll://usr_\` id from the message context, the members
+list, or ref search; your own id comes from \`parall whoami\`.
+
 ## Task Commands
 
 \`\`\`bash
-# List tasks (filterable by status)
+# List tasks (org-wide; filter by status, assignee, or parent)
 parall tasks list
 parall tasks list --status todo
 parall tasks list --status in_progress
+parall tasks list --assignee-id prll://usr_xxx   # first page only (default 20) — for a person's FULL backlog use 'tasks assigned' above
+parall tasks subtasks prll://tsk_xxx             # children of a single parent task
 
-# Create a task
-parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--project-id prll://prj_xxx]
+# Create a task (add --parent-id to make it a SUBTASK of another task)
+parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx]
 
 # Update task status
 parall tasks update prll://tsk_xxx --status in_progress
@@ -21,6 +44,12 @@ parall tasks update prll://tsk_xxx --status done
 parall tasks comments add prll://tsk_xxx --body "Progress update..."
 \`\`\`
 
+Subtasks are just tasks with a parent: create one with \`tasks create --parent-id\`,
+re-parent with \`tasks update --parent-id\`, list a parent's children with
+\`tasks subtasks\`. \`tasks list\` without \`--parent-id\` already returns both
+top-level tasks and subtasks; per-person open work is best fetched with
+\`tasks assigned\` (above).
+
 ## Project Commands
 
 \`\`\`bash

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

@@ -1,2 +1,2 @@
-export declare const PARALL_WIKI_SKILL = "# Parall Wiki\n\nManage organization wikis via the Parall CLI. Auth is pre-configured.\n\n## Browsing (no local state needed)\n\n```bash\nparall wiki list                       # List all wikis\nparall wiki tree <slug>                 # List files and directories\nparall wiki tree <slug> --path docs/    # List a subdirectory\n```\n\n## Editing\n\nWiki editing works on a **local workspace** \u2014 a directory on disk where wiki\nfiles are synced. You sync from the server, edit files locally, then propose\na changeset.\n\n### Step 1: Sync\n\n```bash\nparall wiki sync <slug>\n```\n\nThis downloads wiki files to a local directory. The output includes the\n**absolute mount path** for each wiki (e.g. `synced \u2192 /path/to/workspace/kb`).\n\n### Step 2: Find the mount path\n\nThe sync output JSON contains `synced[].path` \u2014 the absolute path where files\nlive. You can also check it anytime with:\n\n```bash\nparall wiki status <slug>\n```\n\nThe output includes `Mount: /absolute/path/to/<slug>`.\n\nUse this path with `read`, `write`, and `edit` tools. For example, if the mount\nis `/data/.openclaw/workspace/kb`, then `README.md` is at\n`/data/.openclaw/workspace/kb/README.md`.\n\n### Step 3: Edit files\n\nUse standard file tools (`read`, `write`, `edit`) on files under the mount path.\n\n### Step 4: Review changes\n\n```bash\nparall wiki diff <slug>       # Shows unified diff of all local changes\nparall wiki status <slug>     # Shows which files changed with +/- line counts\n```\n\nAlways review before proposing.\n\n### Step 5: Propose changeset\n\n```bash\nparall wiki changeset create <slug> --title \"Description of changes\"\n```\n\nThis uploads your local changes. Unprotected paths auto-merge immediately; the\nCLI prints `auto_merged: true` and refreshes the local manifest. Protected\npaths remain as a changeset for review; follow the returned `next_action`.\n\n## Changeset Management\n\n```bash\nparall wiki changeset list <slug>               # List all changesets\nparall wiki changeset show <changesetId> <slug> # Show detail + feedback\nparall wiki changeset diff <changesetId> <slug> # Show changeset diff\n```\n\nIf a changeset is rejected, fix the files locally and re-propose:\n\n```bash\nparall wiki changeset create <slug> --update <changesetId>\n```\n\nThe title is inherited from the original changeset \u2014 no need to repeat it.\n\n## Handling sync conflicts\n\n`wiki sync` runs a three-way merge. When both you and the server changed the\nsame file, sync **does not overwrite your work**. It leaves your file intact\nand drops the upstream version under `.parall-wiki/conflicts/`:\n\n| Marker | Meaning |\n|--------|---------|\n| `.parall-wiki/conflicts/<path>.remote` | Server has different content (concurrent edit, new file collision, or server changed a file you deleted) |\n| `.parall-wiki/conflicts/<path>.remote-deleted` | Server deleted the file; you still have edits |\n\nstderr prints one line per conflict. Recovery:\n\n**Accept upstream** (drop your edit):\n```bash\ncp .parall-wiki/conflicts/<path>.remote <path>\nparall wiki sync\n```\n\n**Keep yours** (or hand-merge, then propose):\n```bash\n# edit <path> to final content\nparall wiki diff <slug>\nparall wiki changeset create <slug> --title \"Reconcile <path>\"\nparall wiki sync   # fast-forwards after server merges\n```\n\n**Accept server delete** (`.remote-deleted` only):\n```bash\nrm <path>\nparall wiki sync\n```\n\nSync failures (`download`, `shape-conflict`) set exit code 1 and retry on\nnext sync. Conflicts exit 0 \u2014 they need your decision, not a retry.\n\n## Discarding local changes\n\n```bash\nparall wiki reset <slug>      # Restore all files to last synced state\n```\n\n## History\n\n```bash\nparall wiki log <slug>        # Recent wiki operations\n```\n\nCLI success output is JSON; errors may add a plain-text `Request approval:` line on a `PERMISSION_DENIED` \u2014 read both. Run `parall wiki --help` for full options.\n";
+export declare const PARALL_WIKI_SKILL = "# Parall Wiki\n\nManage organization wikis via the Parall CLI. Auth is pre-configured.\n\n## Mental model\n\nWiki editing works on a **local workspace**: `parall wiki sync` downloads the\nwiki into a directory on disk, you edit those files with your normal file\ntools, then `parall wiki changeset create` uploads the result as a proposal.\nThere is no git in the workspace \u2014 your edits are detected by diffing against\nthe synced baseline.\n\nKey facts the commands won't tell you:\n\n- **Workspace location is fixed.** Sync output and `parall wiki status` print\n  the absolute workspace path (`synced \u2192 /path/to/<slug>` / `Mount: ...`).\n  Always address wiki files by that absolute path \u2014 your shell cwd is usually\n  NOT inside the workspace.\n- **Text and binary are two paths.** The workspace + changeset flow is for\n  text (markdown, code, config). Binary assets (images, PDFs, archives) are\n  diff-less \u2014 they don't go in the workspace; use `parall wiki file` (see\n  **Binary files** below). Dropping a binary into the workspace just gets it\n  rejected on propose.\n- **`cat`, `search`, `query`, `outline`, and `section` read your local\n  workspace copy when it exists** \u2014 including your own unproposed edits. Add\n  `--remote` to `cat` to read the server version instead.\n- **`search`/`query` are keyword (lexical) matching**, not semantic search.\n  `query` additionally ranks whole documents \u2014 better for multi-word\n  questions; `search` for a single identifier.\n- The `<wiki>` argument is the slug or ID from `parall wiki list`; with a\n  single wiki in the org it can be omitted.\n\n## Core workflow\n\n```bash\nparall wiki sync                                  # 1. get/update files (prints workspace path)\n# 2. read + edit files under the workspace path with standard file tools\nparall wiki diff <wiki>                            # 3. review exactly what you'll propose\nparall wiki changeset create <wiki> --title \"...\"  # 4. submit\n```\n\nAlways sync before starting and always check `diff` before proposing \u2014 the\nchangeset uploads the full content of every changed file.\n\nUnprotected paths auto-merge immediately (`auto_merged: true`); protected\npaths stay open for human review. Follow the returned `next_action` either way.\n\n## Stale base (server moved since your sync)\n\nIf files changed on the server after your last sync, `changeset create` is\nrejected \u2014 both by a CLI precheck and by the server (409 `STALE_BASE`) \u2014 so\nyou can't silently overwrite someone's concurrent edit. Recovery:\n\n```bash\nparall wiki sync          # pull latest; your local edits are preserved\n# if a file conflicts, resolve it (see next section)\nparall wiki changeset create <wiki> --title \"...\"\n```\n\n## Sync conflicts\n\n`sync` three-way merges. When both you and the server changed the same file,\nyour file is left intact and the upstream copy lands under\n`<workspace>/.parall-wiki/conflicts/`:\n\n| Marker | Meaning |\n|--------|---------|\n| `conflicts/<path>.remote` | Server has different content for `<path>` |\n| `conflicts/<path>.remote-deleted` | Server deleted `<path>`; you still have edits |\n\nAll paths below are relative to the workspace root. Pick one:\n\n```bash\n# Accept upstream (drop your edit):\ncp <workspace>/.parall-wiki/conflicts/<path>.remote <workspace>/<path>\n\n# Keep yours / hand-merge: edit <workspace>/<path> to final content, then\nparall wiki changeset create <wiki> --title \"Reconcile <path>\"\n\n# Accept server delete (.remote-deleted only):\nrm <workspace>/<path>\n```\n\nThen re-run `parall wiki sync` and delete the used marker file. Conflicts\nexit 0 (they need your decision); `failed[]` entries (download error,\nshape-conflict) exit 1 and retry on the next sync.\n\n## Changesets\n\n```bash\nparall wiki changeset list <wiki>\nparall wiki changeset show <changesetId> <wiki>     # status + feedback\nparall wiki changeset diff <changesetId> <wiki>\nparall wiki changeset create <wiki> --update <id>   # re-propose after rejection (title inherited)\n```\n\nRejected: read the feedback (`show` / `status`), fix the files, re-propose\nwith `--update <id>`. Conflict status: `sync`, resolve, then `--update <id>`.\n\nRe-propose REPLACES the changeset's previous contents with your current\nworkspace diff \u2014 to withdraw a file from the proposal, revert it locally\n(restore the synced content) and re-propose; it drops out of the changeset.\n\n## Binary files\n\nImages, PDFs, archives \u2014 anything that can't be diffed \u2014 bypass the workspace\nand changeset-text flow entirely. They never belong in the synced workspace\n(propose rejects them); use `parall wiki file` instead. `cat` is text-only \u2014\nto read a binary's real bytes use `file get` (a plain `sync` only leaves a\nfew-line Git-LFS pointer on disk, since the runtime has no git-lfs).\n\n```bash\n# Maintainer: direct-commit a binary to the default branch (no review)\nparall wiki file upload ./diagram.png docs/assets/diagram.png\n\n# Read a binary's real bytes (LFS pointers resolved server-side) to a file.\n# Always use --output for binaries \u2014 without it the bytes stream to stdout and\n# would flood your context.\nparall wiki file get docs/assets/diagram.png --output ./diagram.png\nparall wiki file get docs/assets/diagram.png --ref <commit-or-branch> --output ./diagram.png   # a specific revision\n\n# Remove a binary from the default branch (git history still has it)\nparall wiki file delete docs/assets/diagram.png\n```\n\n`upload` needs **maintain**; it routes by size automatically (\u22641 MiB inline,\nlarger \u2192 LFS). A text file sent to `upload` is rejected \u2014 that's the changeset\nflow's job.\n\n### Reader: propose markdown that embeds an image\n\nWithout maintain you can still propose a doc with images \u2014 upload the binary\ninto your **changeset's** branch (read + author), not the default branch:\n\n```bash\nparall wiki sync\n# edit a .md in the workspace to add  ![alt](assets/foo.png)\nparall wiki changeset create <wiki> --title \"Add foo diagram\"          # creates the changeset (note its id)\nparall wiki file upload ./foo.png assets/foo.png <wiki> --changeset <changesetId>\n# leave it for a maintainer to merge \u2014 both the markdown and the image squash in together\n```\n\nDo the markdown `changeset create` first so the changeset exists, then attach\nthe image to it. Don't re-propose (`--update`) after attaching a binary \u2014\nre-propose replays only the text workspace and the server rejects dropping the\nattached binary (422 `REPLACE_HAS_BINARY`).\n\n## Discovery & history\n\n```bash\nparall wiki query \"how is auth configured\" <wiki>   # multi-word lookup (query FIRST, wiki second)\nparall wiki search \"JWT\" <wiki>                     # single keyword (query FIRST, wiki second)\nparall wiki outline <wiki> --path docs/             # heading structure\nparall wiki cat docs/auth.md <wiki>                 # print a file (--remote for server version)\nparall wiki tree <wiki>                             # list files\nparall wiki log <wiki>                              # recent operations\nparall wiki log <wiki> docs/auth.md                 # per-file commit history\n```\n\n## Permissions\n\nReads and writes are ACL-checked server-side per path. `parall wiki access\n<path>` shows your level for a path. On a `PERMISSION_DENIED`, errors include\na `Request approval:` hint \u2014 use `parall wiki request-access <path> --reason\n\"...\"` to file an approval card for a maintainer, then re-sync after approval.\n\n## Recovery\n\n```bash\nparall wiki reset <wiki>    # discard ALL local edits, restore last-synced state\nparall wiki status <wiki>   # local changes + your changesets, anytime\n```\n\nCLI success output is JSON on stdout (human summary on stderr); errors state\nthe reason and the next step \u2014 follow them. `parall wiki --help` for the\nfull command list.\n";
 //# sourceMappingURL=parall-wiki.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"parall-wiki.d.ts","sourceRoot":"","sources":["../../src/skills/parall-wiki.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,o4HAkI7B,CAAC"}
+{"version":3,"file":"parall-wiki.d.ts","sourceRoot":"","sources":["../../src/skills/parall-wiki.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,8wPAgL7B,CAAC"}