@parall/agent-core 1.34.0 → 1.36.0

package/src/skills/parall-platform.ts

@@ -156,10 +156,16 @@ Every entity is addressable with a \`prll://\` URI. Common prefixes you'll see i
 | \`prll://prj_\` | Project | parall-tasks |
 | \`prll://sch_\` | Schedule (time trigger) | parall-schedules |
 | \`prll://srn_\` | Schedule run (single fire audit record; carries fire-time snapshot) | parall-schedules |
+| \`prll://xcn_\` | External Trigger Connection (incoming endpoint) | parall-external-triggers |
+| \`prll://xin_\` | External Trigger Event (single incoming event audit record) | parall-external-triggers |
+| \`prll://xtr_\` | External Trigger (incoming trigger configuration) | parall-external-triggers |
+| \`prll://xrn_\` | External Trigger run (single matched dispatch audit record) | parall-external-triggers |
 | \`prll://wik_\` | Wiki | parall-wiki |
 | \`prll://att_\` | Attachment | parall-platform (files) |
 
 When a message or event references \`prll://sch_xxx\` or \`prll://srn_xxx\`, or when you receive \`[Event: schedule.fired]\`, switch to the **parall-schedules** skill for the CLI commands (create / list / pause / resume / cancel / runs).
 
+When a message or event references \`prll://xcn_xxx\`, \`prll://xin_xxx\`, \`prll://xtr_xxx\`, or \`prll://xrn_xxx\`, or when you receive \`[Event: external.trigger]\`, switch to the **parall-external-triggers** skill for the CLI commands (connections / triggers / events / runs).
+
 CLI success output is JSON. Errors print a JSON line (\`{"error","status","code",...}\`) and, on a \`PERMISSION_DENIED\`, may add a plain-text \`Request approval:\` line — read both.
 `;

package/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

@@ -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/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;