@parall/agent-core 1.34.0 → 1.36.0

package/dist/skills/parall-wiki.js

@@ -2,130 +2,176 @@ export const PARALL_WIKI_SKILL = `# Parall Wiki
 
 Manage organization wikis via the Parall CLI. Auth is pre-configured.
 
-## Browsing (no local state needed)
+## Mental model
+
+Wiki editing works on a **local workspace**: \`parall wiki sync\` downloads the
+wiki into a directory on disk, you edit those files with your normal file
+tools, then \`parall wiki changeset create\` uploads the result as a proposal.
+There is no git in the workspace — your edits are detected by diffing against
+the synced baseline.
+
+Key facts the commands won't tell you:
+
+- **Workspace location is fixed.** Sync output and \`parall wiki status\` print
+  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 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.
+- **\`search\`/\`query\` are keyword (lexical) matching**, not semantic search.
+  \`query\` additionally ranks whole documents — better for multi-word
+  questions; \`search\` for a single identifier.
+- The \`<wiki>\` argument is the slug or ID from \`parall wiki list\`; with a
+  single wiki in the org it can be omitted.
+
+## Core workflow
 
 \`\`\`bash
-parall wiki list                       # List all wikis
-parall wiki tree <slug>                 # List files and directories
-parall wiki tree <slug> --path docs/    # List a subdirectory
+parall wiki sync                                  # 1. get/update files (prints workspace path)
+# 2. read + edit files under the workspace path with standard file tools
+parall wiki diff <wiki>                            # 3. review exactly what you'll propose
+parall wiki changeset create <wiki> --title "..."  # 4. submit
 \`\`\`
 
-## Editing
+Always sync before starting and always check \`diff\` before proposing — the
+changeset uploads the full content of every changed file.
 
-Wiki editing works on a **local workspace** — a directory on disk where wiki
-files are synced. You sync from the server, edit files locally, then propose
-a changeset.
+Unprotected paths auto-merge immediately (\`auto_merged: true\`); protected
+paths stay open for human review. Follow the returned \`next_action\` either way.
 
-### Step 1: Sync
+## Stale base (server moved since your sync)
 
-\`\`\`bash
-parall wiki sync <slug>
-\`\`\`
-
-This downloads wiki files to a local directory. The output includes the
-**absolute mount path** for each wiki (e.g. \`synced → /path/to/workspace/kb\`).
-
-### Step 2: Find the mount path
-
-The sync output JSON contains \`synced[].path\` — the absolute path where files
-live. You can also check it anytime with:
+If files changed on the server after your last sync, \`changeset create\` is
+rejected — both by a CLI precheck and by the server (409 \`STALE_BASE\`) — so
+you can't silently overwrite someone's concurrent edit. Recovery:
 
 \`\`\`bash
-parall wiki status <slug>
+parall wiki sync          # pull latest; your local edits are preserved
+# if a file conflicts, resolve it (see next section)
+parall wiki changeset create <wiki> --title "..."
 \`\`\`
 
-The output includes \`Mount: /absolute/path/to/<slug>\`.
-
-Use this path with \`read\`, \`write\`, and \`edit\` tools. For example, if the mount
-is \`/data/.openclaw/workspace/kb\`, then \`README.md\` is at
-\`/data/.openclaw/workspace/kb/README.md\`.
+## Sync conflicts
 
-### Step 3: Edit files
+\`sync\` three-way merges. When both you and the server changed the same file,
+your file is left intact and the upstream copy lands under
+\`<workspace>/.parall-wiki/conflicts/\`:
 
-Use standard file tools (\`read\`, \`write\`, \`edit\`) on files under the mount path.
+| Marker | Meaning |
+|--------|---------|
+| \`conflicts/<path>.remote\` | Server has different content for \`<path>\` |
+| \`conflicts/<path>.remote-deleted\` | Server deleted \`<path>\`; you still have edits |
 
-### Step 4: Review changes
+All paths below are relative to the workspace root. Pick one:
 
 \`\`\`bash
-parall wiki diff <slug>       # Shows unified diff of all local changes
-parall wiki status <slug>     # Shows which files changed with +/- line counts
+# Accept upstream (drop your edit):
+cp <workspace>/.parall-wiki/conflicts/<path>.remote <workspace>/<path>
+
+# Keep yours / hand-merge: edit <workspace>/<path> to final content, then
+parall wiki changeset create <wiki> --title "Reconcile <path>"
+
+# Accept server delete (.remote-deleted only):
+rm <workspace>/<path>
 \`\`\`
 
-Always review before proposing.
+Then re-run \`parall wiki sync\` and delete the used marker file. Conflicts
+exit 0 (they need your decision); \`failed[]\` entries (download error,
+shape-conflict) exit 1 and retry on the next sync.
 
-### Step 5: Propose changeset
+## Changesets
 
 \`\`\`bash
-parall wiki changeset create <slug> --title "Description of changes"
+parall wiki changeset list <wiki>
+parall wiki changeset show <changesetId> <wiki>     # status + feedback
+parall wiki changeset diff <changesetId> <wiki>
+parall wiki changeset create <wiki> --update <id>   # re-propose after rejection (title inherited)
 \`\`\`
 
-This uploads your local changes. Unprotected paths auto-merge immediately; the
-CLI prints \`auto_merged: true\` and refreshes the local manifest. Protected
-paths remain as a changeset for review; follow the returned \`next_action\`.
+Rejected: read the feedback (\`show\` / \`status\`), fix the files, re-propose
+with \`--update <id>\`. Conflict status: \`sync\`, resolve, then \`--update <id>\`.
 
-## Changeset Management
+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.
 
-\`\`\`bash
-parall wiki changeset list <slug>               # List all changesets
-parall wiki changeset show <changesetId> <slug> # Show detail + feedback
-parall wiki changeset diff <changesetId> <slug> # Show changeset diff
-\`\`\`
+## Binary files
 
-If a changeset is rejected, fix the files locally and re-propose:
+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
-parall wiki changeset create <slug> --update <changesetId>
-\`\`\`
+# Maintainer: direct-commit a binary to the default branch (no review)
+parall wiki file upload ./diagram.png docs/assets/diagram.png
 
-The title is inherited from the original changeset — no need to repeat it.
+# 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
 
-## Handling sync conflicts
+# Remove a binary from the default branch (git history still has it)
+parall wiki file delete docs/assets/diagram.png
+\`\`\`
 
-\`wiki sync\` runs a three-way merge. When both you and the server changed the
-same file, sync **does not overwrite your work**. It leaves your file intact
-and drops the upstream version under \`.parall-wiki/conflicts/\`:
+\`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.
 
-| Marker | Meaning |
-|--------|---------|
-| \`.parall-wiki/conflicts/<path>.remote\` | Server has different content (concurrent edit, new file collision, or server changed a file you deleted) |
-| \`.parall-wiki/conflicts/<path>.remote-deleted\` | Server deleted the file; you still have edits |
+### Reader: propose markdown that embeds an image
 
-stderr prints one line per conflict. Recovery:
+Without maintain you can still propose a doc with images — upload the binary
+into your **changeset's** branch (read + author), not the default branch:
 
-**Accept upstream** (drop your edit):
 \`\`\`bash
-cp .parall-wiki/conflicts/<path>.remote <path>
 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
 \`\`\`
 
-**Keep yours** (or hand-merge, then propose):
-\`\`\`bash
-# edit <path> to final content
-parall wiki diff <slug>
-parall wiki changeset create <slug> --title "Reconcile <path>"
-parall wiki sync   # fast-forwards after server merges
-\`\`\`
+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
 
-**Accept server delete** (\`.remote-deleted\` only):
 \`\`\`bash
-rm <path>
-parall wiki sync
+parall wiki query "how is auth configured" <wiki>   # multi-word lookup (query FIRST, wiki second)
+parall wiki search "JWT" <wiki>                     # single keyword (query FIRST, wiki second)
+parall wiki outline <wiki> --path docs/             # heading structure
+parall wiki cat docs/auth.md <wiki>                 # print a file (--remote for server version)
+parall wiki tree <wiki>                             # list files
+parall wiki log <wiki>                              # recent operations
+parall wiki log <wiki> docs/auth.md                 # per-file commit history
 \`\`\`
 
-Sync failures (\`download\`, \`shape-conflict\`) set exit code 1 and retry on
-next sync. Conflicts exit 0 — they need your decision, not a retry.
-
-## Discarding local changes
+## Permissions
 
-\`\`\`bash
-parall wiki reset <slug>      # Restore all files to last synced state
-\`\`\`
+Reads and writes are ACL-checked server-side per path. \`parall wiki access
+<path>\` shows your level for a path. On a \`PERMISSION_DENIED\`, errors include
+a \`Request approval:\` hint — use \`parall wiki request-access <path> --reason
+"..."\` to file an approval card for a maintainer, then re-sync after approval.
 
-## History
+## Recovery
 
 \`\`\`bash
-parall wiki log <slug>        # Recent wiki operations
+parall wiki reset <wiki>    # discard ALL local edits, restore last-synced state
+parall wiki status <wiki>   # local changes + your changesets, anytime
 \`\`\`
 
-CLI success output is JSON; errors may add a plain-text \`Request approval:\` line on a \`PERMISSION_DENIED\` — read both. Run \`parall wiki --help\` for full options.
+CLI success output is JSON on stdout (human summary on stderr); errors state
+the reason and the next step — follow them. \`parall wiki --help\` for the
+full command list.
 `;

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.34.0",
+  "version": "1.36.0",
   "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.34.0"
+    "@parall/sdk": "1.36.0"
   },
   "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),
@@ -1342,6 +1367,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 &&
@@ -1351,7 +1383,7 @@ export class ParallAgentGateway {
             this.dispatchState.mainDispatching = true;
             void this.drainMainBuffer();
           }
-        }, 5000);
+        }, 5000).unref();
       }
     }
   }
@@ -1923,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,
@@ -2074,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\`.
+`;