@parall/parall 1.35.0 → 1.36.1

package/dist/index.bundle.mjs

@@ -26662,6 +26662,25 @@ function buildEventBody(event) {
     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 ? `${event.targetName} (prll://${event.targetId})` : `prll://${event.targetId}`;
@@ -26693,6 +26712,10 @@ function buildSendMessageHint(event) {
   if (event.targetId.startsWith("sch_")) {
     return `
 <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 `
+<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 "";
 }
@@ -27148,6 +27171,17 @@ var ENDPOINTS = {
   SCHEDULE_CANCEL: (orgId, id) => `${API_BASE}/orgs/${orgId}/schedules/${id}/cancel`,
   SCHEDULE_RUNS: (orgId, id) => `${API_BASE}/orgs/${orgId}/schedules/${id}/runs`,
   SCHEDULE_RUN: (orgId, runId) => `${API_BASE}/orgs/${orgId}/schedule_runs/${runId}`,
+  // External triggers (org-scoped incoming integration primitive)
+  EXTERNAL_CONNECTIONS: (orgId) => `${API_BASE}/orgs/${orgId}/external-connections`,
+  EXTERNAL_CONNECTION: (orgId, connectionId) => `${API_BASE}/orgs/${orgId}/external-connections/${connectionId}`,
+  EXTERNAL_CONNECTION_INGRESS_TOKEN_REGENERATE: (orgId, connectionId) => `${API_BASE}/orgs/${orgId}/external-connections/${connectionId}/ingress-token/regenerate`,
+  EXTERNAL_TRIGGER_SCHEMA: (orgId, connectionId) => `${API_BASE}/orgs/${orgId}/external-connections/${connectionId}/trigger-schema`,
+  EXTERNAL_INGRESS_EVENTS: (orgId) => `${API_BASE}/orgs/${orgId}/external-ingress-events`,
+  EXTERNAL_INGRESS_EVENT: (orgId, eventId) => `${API_BASE}/orgs/${orgId}/external-ingress-events/${eventId}`,
+  EXTERNAL_TRIGGERS: (orgId) => `${API_BASE}/orgs/${orgId}/external-triggers`,
+  EXTERNAL_TRIGGER: (orgId, triggerId) => `${API_BASE}/orgs/${orgId}/external-triggers/${triggerId}`,
+  EXTERNAL_TRIGGER_RUNS: (orgId) => `${API_BASE}/orgs/${orgId}/external-trigger-runs`,
+  EXTERNAL_TRIGGER_RUN: (orgId, runId) => `${API_BASE}/orgs/${orgId}/external-trigger-runs/${runId}`,
   // Invitations (org-scoped, admin)
   ORG_INVITATIONS: (orgId) => `${API_BASE}/orgs/${orgId}/invitations`,
   ORG_INVITATION: (orgId, invId) => `${API_BASE}/orgs/${orgId}/invitations/${invId}`,
@@ -27229,6 +27263,7 @@ var ENDPOINTS = {
   // References (org-scoped)
   REFS_RESOLVE: (orgId) => `${API_BASE}/orgs/${orgId}/refs/resolve`,
   REFS_BACKLINKS: (orgId) => `${API_BASE}/orgs/${orgId}/refs/backlinks`,
+  REFS_GRAPH: (orgId) => `${API_BASE}/orgs/${orgId}/refs/graph`,
   REFS_CHECK: (orgId) => `${API_BASE}/orgs/${orgId}/refs/check`,
   // Platform config (agent-scoped, not org-scoped)
   PLATFORM_CONFIG: `${API_BASE}/agents/platform-config`,
@@ -27357,6 +27392,7 @@ var WS_EVENTS = {
 // ../sdk/dist/client.js
 var ParallClient = class _ParallClient {
   baseUrl;
+  wikiBaseUrl;
   token;
   onTokenExpired;
   getRefreshToken;
@@ -27408,12 +27444,22 @@ var ParallClient = class _ParallClient {
   }
   constructor(options = {}) {
     this.baseUrl = options.baseUrl ?? "";
+    this.wikiBaseUrl = options.wikiBaseUrl ?? this.baseUrl;
     this.token = options.token ?? null;
     this.onTokenExpired = options.onTokenExpired;
     this.getRefreshToken = options.getRefreshToken;
     this.setTokens = options.setTokens;
     this.swimlaneName = options.swimlaneName;
   }
+  /**
+   * Pick the origin for a request path: wiki-service base for `/wiki/v1`
+   * endpoints, api base for everything else. The path itself (from ENDPOINTS)
+   * is authoritative, so wiki vs api routing can't drift from how a caller
+   * happens to invoke the client.
+   */
+  baseUrlFor(path7) {
+    return path7.startsWith(WIKI_BASE) ? this.wikiBaseUrl : this.baseUrl;
+  }
   setToken(token) {
     this.token = token;
   }
@@ -27478,7 +27524,7 @@ var ParallClient = class _ParallClient {
     if (!retried) {
       await this.ensureFreshToken(path7);
     }
-    let url = `${this.baseUrl}${path7}`;
+    let url = `${this.baseUrlFor(path7)}${path7}`;
     if (query) {
       const params = new URLSearchParams();
       for (const [key, value] of Object.entries(query)) {
@@ -27550,7 +27596,7 @@ var ParallClient = class _ParallClient {
     void _drop;
     let res;
     try {
-      res = await fetch(`${this.baseUrl}${path7}`, {
+      res = await fetch(`${this.baseUrlFor(path7)}${path7}`, {
         method,
         headers,
         body,
@@ -27710,6 +27756,21 @@ var ParallClient = class _ParallClient {
       q.limit = String(params.limit);
     return this.request("GET", ENDPOINTS.ORG_MEMBER_TASKS(orgId, memberId), void 0, q);
   }
+  // Auto-paginated variant of getMemberTasks: fetches ALL pending tasks
+  // (todo + in_progress) assigned to a member, including subtasks (the
+  // endpoint does not filter parent_id). Powers the CLI `tasks assigned`
+  // command so an agent answering "what's on X's plate" sees the full
+  // backlog, not just the first page.
+  async getMemberTasksAll(orgId, memberId) {
+    const all = [];
+    let cursor;
+    do {
+      const res = await this.getMemberTasks(orgId, memberId, { cursor, limit: 100 });
+      all.push(...res.data);
+      cursor = res.has_more ? res.next_cursor : void 0;
+    } while (cursor);
+    return all;
+  }
   // ---- Invitations ----
   async createInvitation(orgId, email, role) {
     return this.request("POST", ENDPOINTS.ORG_INVITATIONS(orgId), { email, role });
@@ -28139,7 +28200,8 @@ var ParallClient = class _ParallClient {
     const res = await this.request("GET", ENDPOINTS.MACHINES_ME_CLIPS);
     return res.data;
   }
-  /** `GET /machines/me/browser-profiles` — browser profiles hosted by this machine. */
+  /** `GET /machines/me/browser-profiles` — browser profiles hosted by this machine.
+   *  Returns the daemon DTO (carries proxy_password for bb-browser replay). */
   async listMachineBrowserProfiles() {
     const res = await this.request("GET", ENDPOINTS.MACHINES_ME_BROWSER_PROFILES);
     return res.data;
@@ -28299,7 +28361,7 @@ var ParallClient = class _ParallClient {
    * Returns null when the server responds with 304 (config unchanged).
    */
   async getPlatformConfig(currentVersion) {
-    const url = `${this.baseUrl}${ENDPOINTS.PLATFORM_CONFIG}`;
+    const url = `${this.baseUrlFor(ENDPOINTS.PLATFORM_CONFIG)}${ENDPOINTS.PLATFORM_CONFIG}`;
     const extra = {};
     if (currentVersion !== void 0) {
       extra["If-None-Match"] = currentVersion;
@@ -28465,6 +28527,55 @@ var ParallClient = class _ParallClient {
   async getScheduleRun(orgId, runId) {
     return this.request("GET", ENDPOINTS.SCHEDULE_RUN(orgId, runId));
   }
+  // ---- External triggers (org-scoped) ----
+  async createExternalConnection(orgId, input) {
+    return this.request("POST", ENDPOINTS.EXTERNAL_CONNECTIONS(orgId), input);
+  }
+  async listExternalConnections(orgId, filters) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_CONNECTIONS(orgId), void 0, filters);
+  }
+  async getExternalConnection(orgId, connectionId) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_CONNECTION(orgId, connectionId));
+  }
+  async updateExternalConnection(orgId, connectionId, patch) {
+    return this.request("PATCH", ENDPOINTS.EXTERNAL_CONNECTION(orgId, connectionId), patch);
+  }
+  async regenerateExternalConnectionIngressToken(orgId, connectionId) {
+    return this.request("POST", ENDPOINTS.EXTERNAL_CONNECTION_INGRESS_TOKEN_REGENERATE(orgId, connectionId));
+  }
+  async deleteExternalConnection(orgId, connectionId) {
+    return this.request("DELETE", ENDPOINTS.EXTERNAL_CONNECTION(orgId, connectionId));
+  }
+  async getExternalTriggerSchema(orgId, connectionId) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_TRIGGER_SCHEMA(orgId, connectionId));
+  }
+  async listExternalIngressEvents(orgId, filters) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_INGRESS_EVENTS(orgId), void 0, filters);
+  }
+  async getExternalIngressEvent(orgId, eventId) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_INGRESS_EVENT(orgId, eventId));
+  }
+  async createExternalTrigger(orgId, input) {
+    return this.request("POST", ENDPOINTS.EXTERNAL_TRIGGERS(orgId), input);
+  }
+  async listExternalTriggers(orgId, filters) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_TRIGGERS(orgId), void 0, filters);
+  }
+  async getExternalTrigger(orgId, triggerId) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_TRIGGER(orgId, triggerId));
+  }
+  async updateExternalTrigger(orgId, triggerId, patch) {
+    return this.request("PATCH", ENDPOINTS.EXTERNAL_TRIGGER(orgId, triggerId), patch);
+  }
+  async deleteExternalTrigger(orgId, triggerId) {
+    return this.request("DELETE", ENDPOINTS.EXTERNAL_TRIGGER(orgId, triggerId));
+  }
+  async listExternalTriggerRuns(orgId, filters) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_TRIGGER_RUNS(orgId), void 0, filters);
+  }
+  async getExternalTriggerRun(orgId, runId) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_TRIGGER_RUN(orgId, runId));
+  }
   // ---- Wikis (org-scoped) ----
   async createWiki(orgId, data) {
     return this.request("POST", ENDPOINTS.WIKIS(orgId), data);
@@ -28479,8 +28590,35 @@ var ParallClient = class _ParallClient {
   async getWikiTree(orgId, wikiId, params) {
     return this.request("GET", ENDPOINTS.WIKI_TREE(orgId, wikiId), void 0, params);
   }
+  /**
+   * Resolve a server-returned, host-relative media URL (a wiki `signed_url`
+   * like `/wiki/v1/signed/files?token=...`) against this client's base origin,
+   * so it can be dropped straight into a browser `<img>`/`<video>`/`<iframe>`
+   * `src`.
+   *
+   * wiki-service returns these relative on purpose — it doesn't know its own
+   * public origin. A relative `src` resolves against the *page* origin, which
+   * only works when the page and wiki-service share an origin (local dev:
+   * same-origin + Next.js `/wiki/*` proxy). In deployed envs the app
+   * (app.parall.com) and wiki-service (api.parall.com) are different origins,
+   * so `app.parall.com/wiki/v1/signed/files` hits the SPA's own `/wiki/[...]`
+   * catch-all route — an `<iframe>` then recursively renders the whole app
+   * instead of the file. Prefixing with the wiki base (the exact origin every
+   * wiki API request already uses — `baseUrlFor` resolves `/wiki/v1` paths to
+   * `wikiBaseUrl`) makes the URL absolute against the origin that actually
+   * serves the bytes. An empty base (local dev, same-origin proxy) leaves it
+   * relative, preserving the proxy path.
+   */
+  absoluteMediaUrl(url) {
+    if (/^https?:\/\//i.test(url))
+      return url;
+    return `${this.baseUrlFor(url)}${url}`;
+  }
   async getWikiBlob(orgId, wikiId, params) {
-    return this.request("GET", ENDPOINTS.WIKI_BLOB(orgId, wikiId), void 0, params);
+    const blob = await this.request("GET", ENDPOINTS.WIKI_BLOB(orgId, wikiId), void 0, params);
+    if (blob.signed_url)
+      blob.signed_url = this.absoluteMediaUrl(blob.signed_url);
+    return blob;
   }
   async getWikiNodeSections(orgId, wikiId, params) {
     return this.request("GET", ENDPOINTS.WIKI_NODE_SECTIONS(orgId, wikiId), void 0, params);
@@ -28570,7 +28708,10 @@ var ParallClient = class _ParallClient {
    * token — don't leak it.
    */
   async getWikiFilePreviewUrl(orgId, wikiId, params) {
-    return this.request("POST", ENDPOINTS.WIKI_FILE_PREVIEW_URL(orgId, wikiId), params);
+    const res = await this.request("POST", ENDPOINTS.WIKI_FILE_PREVIEW_URL(orgId, wikiId), params);
+    if (res.url)
+      res.url = this.absoluteMediaUrl(res.url);
+    return res;
   }
   // ---- Wiki Path Scopes (AFCS ACL) ----
   async getWikiPathScopes(orgId, wikiId) {
@@ -28647,6 +28788,16 @@ var ParallClient = class _ParallClient {
   async getBacklinks(orgId, params) {
     return this.request("GET", ENDPOINTS.REFS_BACKLINKS(orgId), void 0, params);
   }
+  /**
+   * Bounded multi-hop walk of the prll:// reference graph around `uri`. `uri`
+   * must be an entity-level prll:// URI — a refined URI (path/query/fragment) is
+   * rejected with 400 UNSUPPORTED_REFINED_URI. `depth` is clamped server-side to
+   * [1, 4]; breadth (node/edge counts) is capped server-side and surfaced via
+   * `truncated`. ACL is applied per hop (chat membership + wiki path scope).
+   */
+  async getRefsGraph(orgId, params) {
+    return this.request("GET", ENDPOINTS.REFS_GRAPH(orgId), void 0, params);
+  }
   async checkBrokenRefs(orgId) {
     return this.request("GET", ENDPOINTS.REFS_CHECK(orgId));
   }
@@ -28786,6 +28937,9 @@ var ParallClient = class _ParallClient {
     const resp = await this.request("GET", ENDPOINTS.CLIP_ONLINE(orgId));
     return resp.data;
   }
+  /** Org-wide browser-profile discovery list. Returns the sanitized
+   *  {@link BrowserProfileListItem} shape (not the full domain model), each row
+   *  carrying a per-viewer `can_open` control hint. */
   async listBrowserProfiles(orgId) {
     const resp = await this.request("GET", ENDPOINTS.BROWSER_PROFILES(orgId));
     return resp.data;
@@ -29439,6 +29593,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") {
     return { target_type: "wiki", target_id: event.targetId || void 0 };
   }
@@ -29643,6 +29800,18 @@ var ParallAgentGateway = class {
         } catch (err) {
           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;
@@ -29721,8 +29890,13 @@ var ParallAgentGateway = class {
         target_type: target.target_type,
         target_id: target.target_id,
         content: {
-          trigger_type: event.type === "task" ? "task_assign" : event.type === "task_comment" ? "task_comment" : event.type === "wiki_comment" ? "wiki_comment" : event.type === "schedule" ? "schedule_fire" : event.type === "approval" ? "approval_decided" : "mention",
-          trigger_ref: event.type === "task" ? { task_id: event.targetId } : event.type === "task_comment" ? { comment_id: event.messageId, task_id: event.targetId } : event.type === "wiki_comment" ? { 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 },
+          trigger_type: event.type === "task" ? "task_assign" : event.type === "task_comment" ? "task_comment" : event.type === "wiki_comment" ? "wiki_comment" : event.type === "schedule" ? "schedule_fire" : 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" ? { comment_id: event.messageId, task_id: event.targetId } : event.type === "wiki_comment" ? { comment_id: event.messageId, target_uri: event.replyTargetUri } : event.type === "schedule" ? { schedule_id: event.targetId, run_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),
@@ -30758,6 +30932,62 @@ var ParallAgentGateway = class {
     }
     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 : void 0;
+    const event = {
+      type: "external_trigger",
+      targetId: run.trigger_id,
+      targetName: run.trigger_name || void 0,
+      targetType: "external_trigger",
+      senderId: "system",
+      senderName: "external",
+      messageId: run.id,
+      body: run.agent_input_body ?? "",
+      externalConnectionId: run.connection_id,
+      externalConnectionSourceType: run.connection_source_type || void 0,
+      externalConnectionDisplayName: run.connection_display_name || void 0,
+      externalIngressEventId: run.ingress_event_id,
+      externalIngressEventType: run.ingress_event_type || void 0,
+      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 {
@@ -30868,6 +31098,8 @@ var ParallAgentGateway = class {
             dispatched = await this.handleWikiComment(item.source_id, item.actor_id, item.delivery_reason);
           } else if (item.event_type === "schedule.fire" && item.source_id) {
             dispatched = await this.fetchAndHandleScheduleFire(item.source_id, item.actor_id);
+          } else if (item.event_type === "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);
           } else if (item.event_type === "message" && item.source_id && item.chat_id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/parall",
-  "version": "1.35.0",
+  "version": "1.36.1",
   "description": "OpenClaw channel plugin for Parall IM",
   "license": "MIT",
   "repository": {
@@ -16,8 +16,8 @@
     "openclaw.plugin.json"
   ],
   "dependencies": {
-    "@parall/agent-core": "1.35.0",
-    "@parall/sdk": "1.35.0"
+    "@parall/agent-core": "1.36.1",
+    "@parall/sdk": "1.36.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/skills/parall-external-triggers/SKILL.md

@@ -0,0 +1,92 @@
+---
+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."
+---
+
+# 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/skills/parall-platform/SKILL.md

@@ -69,8 +69,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.
@@ -161,9 +189,37 @@ Every entity is addressable with a `prll://` URI. Common prefixes you'll see in
 | `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/skills/parall-tasks/SKILL.md

@@ -7,16 +7,39 @@ description: "Parall task operations: create, update, comment on, and query task
 
 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
@@ -26,6 +49,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/skills/parall-wiki/SKILL.md

@@ -21,8 +21,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.
@@ -103,6 +106,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