@parall/agent-core 1.35.0 → 1.36.1

package/dist/skills/parall-wiki.js

@@ -16,8 +16,11 @@ Key facts the commands won't tell you:
   the absolute workspace path (\`synced → /path/to/<slug>\` / \`Mount: ...\`).
   Always address wiki files by that absolute path — your shell cwd is usually
   NOT inside the workspace.
-- **Text files only.** Changesets reject binary content. Don't put images or
-  archives in the workspace; binary uploads go through the web UI.
+- **Text and binary are two paths.** The workspace + changeset flow is for
+  text (markdown, code, config). Binary assets (images, PDFs, archives) are
+  diff-less — they don't go in the workspace; use \`parall wiki file\` (see
+  **Binary files** below). Dropping a binary into the workspace just gets it
+  rejected on propose.
 - **\`cat\`, \`search\`, \`query\`, \`outline\`, and \`section\` read your local
   workspace copy when it exists** — including your own unproposed edits. Add
   \`--remote\` to \`cat\` to read the server version instead.
@@ -98,6 +101,50 @@ Re-propose REPLACES the changeset's previous contents with your current
 workspace diff — to withdraw a file from the proposal, revert it locally
 (restore the synced content) and re-propose; it drops out of the changeset.
 
+## Binary files
+
+Images, PDFs, archives — anything that can't be diffed — bypass the workspace
+and changeset-text flow entirely. They never belong in the synced workspace
+(propose rejects them); use \`parall wiki file\` instead. \`cat\` is text-only —
+to read a binary's real bytes use \`file get\` (a plain \`sync\` only leaves a
+few-line Git-LFS pointer on disk, since the runtime has no git-lfs).
+
+\`\`\`bash
+# Maintainer: direct-commit a binary to the default branch (no review)
+parall wiki file upload ./diagram.png docs/assets/diagram.png
+
+# Read a binary's real bytes (LFS pointers resolved server-side) to a file.
+# Always use --output for binaries — without it the bytes stream to stdout and
+# would flood your context.
+parall wiki file get docs/assets/diagram.png --output ./diagram.png
+parall wiki file get docs/assets/diagram.png --ref <commit-or-branch> --output ./diagram.png   # a specific revision
+
+# Remove a binary from the default branch (git history still has it)
+parall wiki file delete docs/assets/diagram.png
+\`\`\`
+
+\`upload\` needs **maintain**; it routes by size automatically (≤1 MiB inline,
+larger → LFS). A text file sent to \`upload\` is rejected — that's the changeset
+flow's job.
+
+### Reader: propose markdown that embeds an image
+
+Without maintain you can still propose a doc with images — upload the binary
+into your **changeset's** branch (read + author), not the default branch:
+
+\`\`\`bash
+parall wiki sync
+# edit a .md in the workspace to add  ![alt](assets/foo.png)
+parall wiki changeset create <wiki> --title "Add foo diagram"          # creates the changeset (note its id)
+parall wiki file upload ./foo.png assets/foo.png <wiki> --changeset <changesetId>
+# leave it for a maintainer to merge — both the markdown and the image squash in together
+\`\`\`
+
+Do the markdown \`changeset create\` first so the changeset exists, then attach
+the image to it. Don't re-propose (\`--update\`) after attaching a binary —
+re-propose replays only the text workspace and the server rejects dropping the
+attached binary (422 \`REPLACE_HAS_BINARY\`).
+
 ## Discovery & history
 
 \`\`\`bash

package/dist/types.d.ts

@@ -26,7 +26,7 @@ export type DispatchState = {
 };
 /** Normalized inbound event from Parall. */
 export type ParallEvent = {
-    type: 'message' | 'task' | 'task_comment' | 'wiki_comment' | 'schedule' | 'approval';
+    type: 'message' | 'task' | 'task_comment' | 'wiki_comment' | 'schedule' | 'external_trigger' | 'approval';
     targetId: string;
     targetName?: string;
     targetType?: string;
@@ -54,10 +54,16 @@ export type ParallEvent = {
     scheduledFireAt?: string;
     /** Fire-time attached_to_uri snapshot, used for schedule events. */
     attachedUri?: string;
+    /** External trigger metadata, used for external_trigger events. */
+    externalConnectionId?: string;
+    externalConnectionSourceType?: string;
+    externalConnectionDisplayName?: string;
+    externalIngressEventId?: string;
+    externalIngressEventType?: string;
     /** Original event timestamp (e.g., message.created_at). When present,
      *  input steps use this instead of server insertion time for ordering. */
     sentAt?: string;
-    ackSourceType?: 'message' | 'task_activity' | 'comment' | 'schedule_run';
+    ackSourceType?: 'message' | 'task_activity' | 'comment' | 'schedule_run' | 'external_trigger_run';
     ackSourceId?: string;
     /** Unread message count in the target chat since agent's last interaction. */
     unreadCount?: number;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,mFAAmF;IACnF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,cAAc,GAAG,cAAc,GAAG,UAAU,GAAG,UAAU,CAAC;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;8EAC0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,CAAC;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,mFAAmF;IACnF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EACA,SAAS,GACT,MAAM,GACN,cAAc,GACd,cAAc,GACd,UAAU,GACV,kBAAkB,GAClB,UAAU,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;8EAC0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,GAAG,sBAAsB,CAAC;IAClG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.35.0",
+  "version": "1.36.1",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "@opentelemetry/sdk-logs": "^0.57.0",
     "@opentelemetry/sdk-metrics": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
-    "@parall/sdk": "1.35.0"
+    "@parall/sdk": "1.36.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/event-format.ts

@@ -89,6 +89,26 @@ export function buildEventBody(event: ParallEvent): string {
     if (event.scheduledFireAt) lines.push(`[Scheduled at: ${sanitizeMeta(event.scheduledFireAt)}]`);
     if (event.attachedUri) 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
@@ -125,6 +145,10 @@ function buildSendMessageHint(event: ParallEvent): string {
     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 '';
 }
 

package/src/gateway-base.ts

@@ -12,6 +12,7 @@ import type {
   Comment,
   DispatchDeliveryReason,
   DispatchNewData,
+  ExternalTriggerRun,
   HelloData,
   MessageNewData,
   ScheduleRun,
@@ -194,6 +195,9 @@ function resolveStepTarget(event: ParallEvent): { target_type: string; target_id
   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 /
@@ -457,6 +461,18 @@ export class ParallAgentGateway {
             `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;
         try {
@@ -570,9 +586,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 }
@@ -582,9 +600,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),
@@ -1930,6 +1955,70 @@ export class ParallAgentGateway {
     return dispatched;
   }
 
+  private async fetchAndHandleExternalTriggerRun(runId: string): Promise<boolean> {
+    let run: ExternalTriggerRun | null = null;
+    try {
+      run = await this.opts.client.getExternalTriggerRun(this.opts.config.org_id, runId);
+    } catch (err: unknown) {
+      const status = (err as { status?: number })?.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);
+  }
+
+  private async handleExternalTriggerRun(run: ExternalTriggerRun): Promise<boolean> {
+    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: ParallEvent = {
+      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: boolean;
+    try {
+      dispatched = await this.handleInboundEvent(event);
+    } catch (err) {
+      this.dispatchedTasks.delete(dedupeKey);
+      throw err;
+    }
+    if (!dispatched) {
+      this.dispatchedTasks.delete(dedupeKey);
+    }
+    return dispatched;
+  }
+
   private async fetchAndHandleApprovalDecided(
     approvalId: string,
     actorId: string | null,
@@ -2081,6 +2170,8 @@ 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,

package/src/skills/index.ts

@@ -5,12 +5,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 { 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 type SkillMeta = { name: string; description: string; content: string };
@@ -40,6 +42,12 @@ export const SKILLS: SkillMeta[] = [
       '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:

package/src/skills/parall-external-triggers.ts

@@ -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/src/skills/parall-platform.ts

@@ -64,8 +64,36 @@ parall machines logs prll://mch_xxx --lines 100
 \`\`\`bash
 parall chats list            # List all chats
 parall messages list prll://cht_xxx # Read chat message history
+parall messages list prll://cht_xxx --since 2026-01-01 # Only messages at/after a date (RFC3339 or YYYY-MM-DD)
 \`\`\`
 
+## Org-Context Search
+
+Before deciding or starting non-trivial work, search the org's real history —
+past discussions, decisions, tasks, and wiki notes — so you don't re-litigate
+settled questions or repeat known mistakes. This searches live org data
+(semantic + keyword), not a local copy, and is permission-filtered to what you
+can see.
+
+\`\`\`bash
+# Semantic + keyword search across messages, tasks, and wiki
+parall search "auth v5 upgrade"
+
+# Restrict entity types (m=message, t=task, w=wiki). --channel narrows the
+# MESSAGE hits to one chat (tasks/wiki are unaffected by it).
+parall search "auth v5 upgrade" --types m,w --channel prll://cht_eng
+
+# Time-box to recent activity (RFC3339 or YYYY-MM-DD). Narrows messages + tasks;
+# wiki is always matched by relevance (the index has no authored timestamp).
+parall search "auth v5 upgrade" --since 2026-01-01
+
+# Narrow wiki hits to a frontmatter document type
+parall search "deploy steps" --types w --wiki-type Runbook
+\`\`\`
+
+Even with zero curated notes, the raw message + task history is searchable — the
+original discussion and its approval/rejection IS the precedent.
+
 ## Sending Messages
 
 Each \`[Event: message.new]\` includes \`[Chat: ... (prll://cht_xxx)]\` — use that chat URI to reply.
@@ -156,10 +184,38 @@ 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).
+
+## References (relationship graph)
+
+\`prll://\` references between entities form a graph — a message cites a task, a
+task cites a wiki page, and so on. Walk it to answer "what is this decision /
+entity connected to". All results are permission-filtered to what you can see.
+
+\`\`\`bash
+# Resolve URIs to entity metadata (titles, status, previews)
+parall refs resolve prll://tsk_xxx prll://wik_xxx
+
+# Single hop — who references X
+parall refs backlinks prll://tsk_xxx
+
+# Multi-hop — the connected sub-graph around X (entity-level URI only — no
+# path/anchor; depth 1–4, default 2)
+parall refs graph prll://tsk_xxx --depth 2
+\`\`\`
+
+\`refs graph\` traverses both directions (inbound + outbound) and returns \`nodes\`
+and \`edges\` with each node's hop \`depth\`. \`truncated: true\` means a size cap clipped
+the result — narrow it with a smaller \`--depth\`.
+
 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/src/skills/parall-tasks.ts

@@ -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/src/skills/parall-wiki.ts

@@ -16,8 +16,11 @@ Key facts the commands won't tell you:
   the absolute workspace path (\`synced → /path/to/<slug>\` / \`Mount: ...\`).
   Always address wiki files by that absolute path — your shell cwd is usually
   NOT inside the workspace.
-- **Text files only.** Changesets reject binary content. Don't put images or
-  archives in the workspace; binary uploads go through the web UI.
+- **Text and binary are two paths.** The workspace + changeset flow is for
+  text (markdown, code, config). Binary assets (images, PDFs, archives) are
+  diff-less — they don't go in the workspace; use \`parall wiki file\` (see
+  **Binary files** below). Dropping a binary into the workspace just gets it
+  rejected on propose.
 - **\`cat\`, \`search\`, \`query\`, \`outline\`, and \`section\` read your local
   workspace copy when it exists** — including your own unproposed edits. Add
   \`--remote\` to \`cat\` to read the server version instead.
@@ -98,6 +101,50 @@ Re-propose REPLACES the changeset's previous contents with your current
 workspace diff — to withdraw a file from the proposal, revert it locally
 (restore the synced content) and re-propose; it drops out of the changeset.
 
+## Binary files
+
+Images, PDFs, archives — anything that can't be diffed — bypass the workspace
+and changeset-text flow entirely. They never belong in the synced workspace
+(propose rejects them); use \`parall wiki file\` instead. \`cat\` is text-only —
+to read a binary's real bytes use \`file get\` (a plain \`sync\` only leaves a
+few-line Git-LFS pointer on disk, since the runtime has no git-lfs).
+
+\`\`\`bash
+# Maintainer: direct-commit a binary to the default branch (no review)
+parall wiki file upload ./diagram.png docs/assets/diagram.png
+
+# Read a binary's real bytes (LFS pointers resolved server-side) to a file.
+# Always use --output for binaries — without it the bytes stream to stdout and
+# would flood your context.
+parall wiki file get docs/assets/diagram.png --output ./diagram.png
+parall wiki file get docs/assets/diagram.png --ref <commit-or-branch> --output ./diagram.png   # a specific revision
+
+# Remove a binary from the default branch (git history still has it)
+parall wiki file delete docs/assets/diagram.png
+\`\`\`
+
+\`upload\` needs **maintain**; it routes by size automatically (≤1 MiB inline,
+larger → LFS). A text file sent to \`upload\` is rejected — that's the changeset
+flow's job.
+
+### Reader: propose markdown that embeds an image
+
+Without maintain you can still propose a doc with images — upload the binary
+into your **changeset's** branch (read + author), not the default branch:
+
+\`\`\`bash
+parall wiki sync
+# edit a .md in the workspace to add  ![alt](assets/foo.png)
+parall wiki changeset create <wiki> --title "Add foo diagram"          # creates the changeset (note its id)
+parall wiki file upload ./foo.png assets/foo.png <wiki> --changeset <changesetId>
+# leave it for a maintainer to merge — both the markdown and the image squash in together
+\`\`\`
+
+Do the markdown \`changeset create\` first so the changeset exists, then attach
+the image to it. Don't re-propose (\`--update\`) after attaching a binary —
+re-propose replays only the text workspace and the server rejects dropping the
+attached binary (422 \`REPLACE_HAS_BINARY\`).
+
 ## Discovery & history
 
 \`\`\`bash

package/src/types.ts

@@ -24,7 +24,14 @@ export type DispatchState = {
 
 /** Normalized inbound event from Parall. */
 export type ParallEvent = {
-  type: 'message' | 'task' | 'task_comment' | 'wiki_comment' | 'schedule' | 'approval';
+  type:
+    | 'message'
+    | 'task'
+    | 'task_comment'
+    | 'wiki_comment'
+    | 'schedule'
+    | 'external_trigger'
+    | 'approval';
   targetId: string;
   targetName?: string;
   targetType?: string;
@@ -52,10 +59,16 @@ export type ParallEvent = {
   scheduledFireAt?: string;
   /** Fire-time attached_to_uri snapshot, used for schedule events. */
   attachedUri?: string;
+  /** External trigger metadata, used for external_trigger events. */
+  externalConnectionId?: string;
+  externalConnectionSourceType?: string;
+  externalConnectionDisplayName?: string;
+  externalIngressEventId?: string;
+  externalIngressEventType?: string;
   /** Original event timestamp (e.g., message.created_at). When present,
    *  input steps use this instead of server insertion time for ordering. */
   sentAt?: string;
-  ackSourceType?: 'message' | 'task_activity' | 'comment' | 'schedule_run';
+  ackSourceType?: 'message' | 'task_activity' | 'comment' | 'schedule_run' | 'external_trigger_run';
   ackSourceId?: string;
   /** Unread message count in the target chat since agent's last interaction. */
   unreadCount?: number;