@parall/agent-core 1.42.0 → 1.43.0

package/dist/prompt-fragments.js

@@ -197,10 +197,10 @@ resolves and renders the entity title automatically.
 
     prll://usr_xxx          user          prll://prj_xxx          project
     prll://tsk_xxx          task          prll://wik_xxx          wiki
-    prll://msg_xxx          message       prll://tcm_xxx          task comment
-    prll://cht_xxx          chat          prll://ase_xxx          agent session
-    prll://att_xxx          attachment    prll://sch_xxx          schedule
-                                          prll://srn_xxx          schedule run
+    prll://msg_xxx          message       prll://cmt_xxx          comment
+    prll://cht_xxx          chat          prll://tcm_xxx          task comment (legacy)
+    prll://att_xxx          attachment    prll://ase_xxx          agent session
+    prll://sch_xxx          schedule      prll://srn_xxx          schedule run
 
 **Wiki** — path is file path, fragment is a typed anchor:
 
@@ -246,15 +246,37 @@ session already has continuity, so skip the fetch unless something is unclear.
 
 Same pattern for any other entity referenced in the event: \`tasks get\`,
 \`projects get\`, \`users get\`, \`chats get\`. Follow the reflink, don't ask.
+When one entity isn't enough — you need what's *around* it — walk the
+reference graph instead of guessing (see "Walk the reference graph" below).
 
 ### Find context with search first
 
 Reach for unified semantic search before paging chat history:
 
-    parall search "pricing decision june" [--limit 10]
+    parall search "pricing decision june" --limit 10
 
-It spans messages, tasks, and wiki. Page \`messages list\` only for the verbatim
-recent flow of one chat, not for discovery.
+It spans messages, tasks, wiki, and comments. Page \`messages list\` only for the
+verbatim recent flow of one chat, not for discovery.
+
+### Walk the reference graph
+
+References form a traversable graph, and you can query it — don't stop at
+fetching entities one by one:
+
+    # entity metadata (title, status, preview)
+    parall refs resolve prll://tsk_xxx prll://wik_xxx
+    # who references this entity
+    parall refs backlinks prll://tsk_xxx
+    # connected sub-graph around it
+    parall refs graph prll://tsk_xxx --depth 2
+
+Use \`refs backlinks\` when you need "where is this discussed / used"; use
+\`refs graph\` when you need the full picture around an entity (related tasks,
+docs, conversations — edges carry the author's annotation for why they linked).
+Then \`refs resolve\` the interesting node URIs in one batch to get titles and
+status. \`refs graph\` takes entity-level URIs only (\`prll://wik_xxx\`, not
+\`prll://wik_xxx/docs/a.md\`). All results are filtered to what you can see.
+Details: parall-platform skill.
 
 ### File attachments
 

package/dist/skills/index.js

@@ -15,7 +15,7 @@ import { PARALL_CLIPS_SKILL } from './parall-clips.js';
 export const SKILLS = [
     {
         name: 'parall-platform',
-        description: "Parall platform queries and lightweight agent provisioning: list org members, agents, chats, read message history, check identity, or create another agent. Use when: user asks about org members, who's online, chat history, agent list, creating an agent, or identity/auth questions.",
+        description: "Parall platform queries and lightweight agent provisioning: list org members, agents, chats, read message history, check identity, create another agent, or walk the prll:// reference graph (resolve URIs, backlinks, multi-hop graph). Use when: user asks about org members, who's online, chat history, agent list, creating an agent, identity/auth questions, or you need to find what an entity is connected to / who references it.",
         content: PARALL_PLATFORM_SKILL,
     },
     {

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

@@ -1,2 +1,2 @@
-export declare const PARALL_PLATFORM_SKILL = "# Parall Platform\n\nQuery organization data via the Parall CLI. Auth is pre-configured.\n\n## Identity\n\n```bash\nparall whoami\n```\n\n## Members & Agents\n\n```bash\nparall members list          # All org members (humans + agents)\nparall agents list           # Agents only\nparall users get prll://usr_xxx     # Get user details by ID\n```\n\nCreate a hosted agent when the user asks for a Parall-managed runtime. Hosted\nprovisioning is asynchronous: creation means the agent identity, API key, and\nmachine record were accepted, not that the runtime is online yet. Use `--wait`\nto wait until the machine reaches `running`, and use `--wait-online` when the\ntask requires the child agent to be connected before you report completion.\nFor hosted agents, use `--discard-api-key`; the server injects the one-time key\ninto the hosted runtime, so the parent agent must not print or persist it.\n\nCreate a self-hosted agent only when the runtime will be connected outside\nParall-managed compute. In that case, write the one-time `api_key` to\n`--api-key-file` so it is not captured in tool-result logs. Treat `api_key` as a\nsecret: do not print, read aloud, post it in shared chats, or echo the file\ncontents. Include the `user.id` in normal responses, and pass the key file only\nthrough an explicit secure runtime handoff when connection is required. Never\nuse `--show-api-key` from an agent runtime. Agent callers cannot set provider\noverrides until the dedicated fine-grained permission flow lands.\n\n```bash\n# Hosted runtime (Parall-managed compute)\nparall agents create \\\n  --name \"Research Agent\" \\\n  --runtime-type codex \\\n  --machine-type cloud \\\n  --machine-label standard \\\n  --discard-api-key \\\n  --wait \\\n  --wait-online\n\n# Self-hosted runtime\nparall agents create --name \"Research Agent\" --runtime-type codex --api-key-file /tmp/research-agent.api-key\n```\n\nInspect hosted provisioning directly when a create command returns before the\nruntime is online, or when you need logs for a failed machine. If `agents create`\nexits non-zero after creating a hosted agent, read the printed `user.id` and\n`machine.id`, then use these commands to decide whether to wait, inspect logs,\nor report the failed machine for retry.\n\n```bash\nparall machines status prll://mch_xxx\nparall machines logs prll://mch_xxx --lines 100\n```\n\n## Chats & Messages\n\n```bash\nparall chats list            # List all chats\nparall messages list prll://cht_xxx # Read chat message history\nparall messages list prll://cht_xxx --since 2026-01-01 # Only messages at/after a date (RFC3339 or YYYY-MM-DD)\n```\n\n## Org-Context Search\n\nBefore deciding or starting non-trivial work, search the org's real history \u2014\npast discussions, decisions, tasks, and wiki notes \u2014 so you don't re-litigate\nsettled questions or repeat known mistakes. This searches live org data\n(semantic + keyword), not a local copy, and is permission-filtered to what you\ncan see.\n\n```bash\n# Semantic + keyword search across messages, tasks, and wiki\nparall search \"auth v5 upgrade\"\n\n# Restrict entity types (m=message, t=task, w=wiki). --channel narrows the\n# MESSAGE hits to one chat (tasks/wiki are unaffected by it).\nparall search \"auth v5 upgrade\" --types m,w --channel prll://cht_eng\n\n# Time-box to recent activity (RFC3339 or YYYY-MM-DD). Narrows messages + tasks;\n# wiki is always matched by relevance (the index has no authored timestamp).\nparall search \"auth v5 upgrade\" --since 2026-01-01\n\n# Narrow wiki hits to a frontmatter document type\nparall search \"deploy steps\" --types w --wiki-type Runbook\n```\n\nEven with zero curated notes, the raw message + task history is searchable \u2014 the\noriginal discussion and its approval/rejection IS the precedent.\n\n## Sending Messages\n\nEach `[Event: message.new]` includes `[Chat: ... (prll://cht_xxx)]` \u2014 use that chat URI to reply.\n\n> **How you pass the message body matters \u2014 your command runs through a shell.**\n> Inside double quotes the shell expands `$`, backticks, and `$(...)` *before*\n> the CLI sees them: `--text \"That costs $1,000\"` sends `That costs ,000`, and\n> `--text \"$(cmd)\"` runs `cmd`. Single quotes instead break on apostrophes\n> (`I'm`, `don't`). So do **not** wrap real message content in quotes \u2014 pass it\n> through `--text-file` (a written file, or a quoted heredoc `<<'EOF'` that\n> disables all expansion). Reserve `--text \"...\"` for short literals with no\n> `$`, backtick, or apostrophe.\n\n```bash\n# One-off reply \u2192 quoted heredoc into stdin. The quoted delimiter <<'EOF'\n# disables ALL shell expansion, so $, backticks and apostrophes pass verbatim.\nparall messages send prll://cht_xxx --text-file - <<'PARALL_EOF'\nSure \u2014 that's $1,000, and $(whoami) stays literal. I'm on it.\nPARALL_EOF\n\n# Longer / multi-line reply \u2192 write it with your file tool (no shell touches\n# the body), then point --text-file at the file.\nparall messages send prll://cht_xxx --text-file /tmp/reply.md\n\n# Short literal with no $, backtick, or apostrophe \u2192 --text is fine.\nparall messages send prll://cht_xxx --text \"On it\"\n\n# Direct message by user URI or display name (same --text-file / heredoc rules)\nparall dm prll://usr_xxx --text-file /tmp/reply.md\nparall dm \"Alice\" --text \"Hello\"\n\n# Thread reply\nparall messages send prll://cht_xxx --text-file /tmp/reply.md --thread-root-id 01JWC...\n\n# FYI message (no response expected \u2014 the recipient sees `[Hint: no_reply]`)\nparall messages send prll://cht_xxx --text \"FYI: done\" --no-reply\n\n# Silence this turn entirely \u2014 no chat message produced. Use when you receive\n# `[Hint: no_reply]` or otherwise decide the turn needs no visible reply.\n# Run BEFORE any `messages send` / `dm`; those still deliver real messages.\nparall no-reply --reason \"ack only, nothing to add\"\n```\n\n## Files & Attachments\n\nAttachments appear in events as `[Attachment: prll://att_xxx | mime | size | name]`.\n\n```bash\n# Download an attachment\nparall files download att_xxx --output /tmp/file.png\n\n# Upload a file (returns attachment_id)\nparall files upload /tmp/report.pdf\n\n# Send a message with a file\nparall messages send prll://cht_xxx --file /tmp/output.png --text \"Done\"\n\n# Send an existing attachment to another chat\nparall messages send prll://cht_xxx --attachment att_xxx --text \"See attached\"\n\n# DM with a file\nparall dm \"Alice\" --file /tmp/report.pdf --text \"Report attached\"\n```\n\n`--file` and `--attachment` are mutually exclusive. A caption (`--text` for\nshort literals, or `--text-file` for anything with `$`, backticks, or quotes)\ncan be combined with either.\n\n## Approvals\n\nWhen a CLI command returns a `PERMISSION_DENIED` error, the output includes the denied `action` and `resource_uri`. Whether that action can be approved is decided by the server (there is no fixed allowlist):\n- If it IS approvable, a `Request approval:` line with a `parall approvals request` command follows \u2014 fill in the placeholders it shows (`--chat`, `--title`, `--reason`) and run it.\n- If it is NOT approvable, the output says so \u2014 ask a human with permission instead of requesting approval.\n\nA different `INVALID_TARGET` error means you addressed the wrong kind of thing (e.g. a `usr_` id where a chat is expected). Follow the message (e.g. use `parall dm` to message a user) \u2014 do not request approval for it.\n\n```bash\n# Request approval (use action and resource_uri from the error)\nparall approvals request --action chat.archive --resource prll://cht_xxx --chat prll://cht_yyy --title \"Archive old channel\" --reason \"No activity in 6 months\"\n\n# Check a specific approval's status\nparall approvals get prll://apr_xxx\n\n# Wait for a decision (blocks until approved/rejected/timeout)\nparall approvals wait prll://apr_xxx --timeout 300\n\n# List all your pending approvals\nparall approvals list\n\n# List available approvable actions\nparall approvals actions\n\n# Cancel a pending request you made\nparall approvals cancel prll://apr_xxx\n```\n\nOnly request approval after receiving an actual `PERMISSION_DENIED` error \u2014 never preemptively. The `--chat` flag specifies where the approval card appears; use the chat where the conversation is happening.\n\n## Reference URIs\n\nEvery entity is addressable with a `prll://` URI. Common prefixes you'll see in events, messages, and schedule descriptions:\n\n| Prefix | Entity | Skill |\n|--------|--------|-------|\n| `prll://usr_` | User (human or agent) | parall-platform |\n| `prll://cht_` | Chat | parall-platform |\n| `prll://msg_` | Message | parall-platform |\n| `prll://tsk_` | Task | parall-tasks |\n| `prll://prj_` | Project | parall-tasks |\n| `prll://sch_` | Schedule (time trigger) | parall-schedules |\n| `prll://srn_` | Schedule run (single fire audit record; carries fire-time snapshot) | parall-schedules |\n| `prll://xcn_` | External Trigger Connection (incoming endpoint) | parall-external-triggers |\n| `prll://xin_` | External Trigger Event (single incoming event audit record) | parall-external-triggers |\n| `prll://xtr_` | External Trigger (incoming trigger configuration) | parall-external-triggers |\n| `prll://xrn_` | External Trigger run (single matched dispatch audit record) | parall-external-triggers |\n| `prll://wik_` | Wiki | parall-wiki |\n| `prll://att_` | Attachment | parall-platform (files) |\n\nWhen a message or event references `prll://sch_xxx` or `prll://srn_xxx`, or when you receive `[Event: schedule.fired]`, switch to the **parall-schedules** skill for the CLI commands (create / list / pause / resume / cancel / runs).\n\nWhen a message or event references `prll://xcn_xxx`, `prll://xin_xxx`, `prll://xtr_xxx`, or `prll://xrn_xxx`, or when you receive `[Event: external.trigger]`, switch to the **parall-external-triggers** skill for the CLI commands (connections / triggers / events / runs).\n\n## References (relationship graph)\n\n`prll://` references between entities form a graph \u2014 a message cites a task, a\ntask cites a wiki page, and so on. Walk it to answer \"what is this decision /\nentity connected to\". All results are permission-filtered to what you can see.\n\n```bash\n# Resolve URIs to entity metadata (titles, status, previews)\nparall refs resolve prll://tsk_xxx prll://wik_xxx\n\n# Single hop \u2014 who references X\nparall refs backlinks prll://tsk_xxx\n\n# Multi-hop \u2014 the connected sub-graph around X (entity-level URI only \u2014 no\n# path/anchor; depth 1\u20134, default 2)\nparall refs graph prll://tsk_xxx --depth 2\n```\n\n`refs graph` traverses both directions (inbound + outbound) and returns `nodes`\nand `edges` with each node's hop `depth`. `truncated: true` means a size cap clipped\nthe result \u2014 narrow it with a smaller `--depth`.\n\nCLI success output is JSON. Errors print a JSON line (`{\"error\",\"status\",\"code\",...}`) and, on a `PERMISSION_DENIED`, may add a plain-text `Request approval:` line \u2014 read both.\n";
+export declare const PARALL_PLATFORM_SKILL = "# Parall Platform\n\nQuery organization data via the Parall CLI. Auth is pre-configured.\n\n## Identity\n\n```bash\nparall whoami\n```\n\n## Members & Agents\n\n```bash\nparall members list          # All org members (humans + agents)\nparall agents list           # Agents only\nparall users get prll://usr_xxx     # Get user details by ID\n```\n\nCreate a hosted agent when the user asks for a Parall-managed runtime. Hosted\nprovisioning is asynchronous: creation means the agent identity, API key, and\nmachine record were accepted, not that the runtime is online yet. Use `--wait`\nto wait until the machine reaches `running`, and use `--wait-online` when the\ntask requires the child agent to be connected before you report completion.\nFor hosted agents, use `--discard-api-key`; the server injects the one-time key\ninto the hosted runtime, so the parent agent must not print or persist it.\n\nCreate a self-hosted agent only when the runtime will be connected outside\nParall-managed compute. In that case, write the one-time `api_key` to\n`--api-key-file` so it is not captured in tool-result logs. Treat `api_key` as a\nsecret: do not print, read aloud, post it in shared chats, or echo the file\ncontents. Include the `user.id` in normal responses, and pass the key file only\nthrough an explicit secure runtime handoff when connection is required. Never\nuse `--show-api-key` from an agent runtime. Agent callers cannot set provider\noverrides until the dedicated fine-grained permission flow lands.\n\n```bash\n# Hosted runtime (Parall-managed compute)\nparall agents create \\\n  --name \"Research Agent\" \\\n  --runtime-type codex \\\n  --machine-type cloud \\\n  --machine-label standard \\\n  --discard-api-key \\\n  --wait \\\n  --wait-online\n\n# Self-hosted runtime\nparall agents create --name \"Research Agent\" --runtime-type codex --api-key-file /tmp/research-agent.api-key\n```\n\nInspect hosted provisioning directly when a create command returns before the\nruntime is online, or when you need logs for a failed machine. If `agents create`\nexits non-zero after creating a hosted agent, read the printed `user.id` and\n`machine.id`, then use these commands to decide whether to wait, inspect logs,\nor report the failed machine for retry.\n\n```bash\nparall machines status prll://mch_xxx\nparall machines logs prll://mch_xxx --lines 100\n```\n\n## Chats & Messages\n\n```bash\nparall chats list            # List all chats\nparall messages list prll://cht_xxx # Read chat message history\nparall messages list prll://cht_xxx --since 2026-01-01 # Only messages at/after a date (RFC3339 or YYYY-MM-DD)\n```\n\n## Org-Context Search\n\nBefore deciding or starting non-trivial work, search the org's real history \u2014\npast discussions, decisions, tasks, and wiki notes \u2014 so you don't re-litigate\nsettled questions or repeat known mistakes. This searches live org data\n(semantic + keyword), not a local copy, and is permission-filtered to what you\ncan see.\n\n```bash\n# Semantic + keyword search across messages, tasks, wiki, and comments\nparall search \"auth v5 upgrade\"\n\n# Restrict entity types (m=message, t=task, w=wiki, c=comment). --channel\n# narrows the MESSAGE hits to one chat (tasks/wiki/comments are unaffected).\nparall search \"auth v5 upgrade\" --types m,w --channel prll://cht_eng\n\n# Time-box to recent activity (RFC3339 or YYYY-MM-DD). Narrows messages + tasks;\n# wiki is always matched by relevance (the index has no authored timestamp).\nparall search \"auth v5 upgrade\" --since 2026-01-01\n\n# Narrow wiki hits to a frontmatter document type\nparall search \"deploy steps\" --types w --wiki-type Runbook\n```\n\nEven with zero curated notes, the raw message + task history is searchable \u2014 the\noriginal discussion and its approval/rejection IS the precedent.\n\n## Sending Messages\n\nEach `[Event: message.new]` includes `[Chat: ... (prll://cht_xxx)]` \u2014 use that chat URI to reply.\n\n> **How you pass the message body matters \u2014 your command runs through a shell.**\n> Inside double quotes the shell expands `$`, backticks, and `$(...)` *before*\n> the CLI sees them: `--text \"That costs $1,000\"` sends `That costs ,000`, and\n> `--text \"$(cmd)\"` runs `cmd`. Single quotes instead break on apostrophes\n> (`I'm`, `don't`). So do **not** wrap real message content in quotes \u2014 pass it\n> through `--text-file` (a written file, or a quoted heredoc `<<'EOF'` that\n> disables all expansion). Reserve `--text \"...\"` for short literals with no\n> `$`, backtick, or apostrophe.\n\n```bash\n# One-off reply \u2192 quoted heredoc into stdin. The quoted delimiter <<'EOF'\n# disables ALL shell expansion, so $, backticks and apostrophes pass verbatim.\nparall messages send prll://cht_xxx --text-file - <<'PARALL_EOF'\nSure \u2014 that's $1,000, and $(whoami) stays literal. I'm on it.\nPARALL_EOF\n\n# Longer / multi-line reply \u2192 write it with your file tool (no shell touches\n# the body), then point --text-file at the file.\nparall messages send prll://cht_xxx --text-file /tmp/reply.md\n\n# Short literal with no $, backtick, or apostrophe \u2192 --text is fine.\nparall messages send prll://cht_xxx --text \"On it\"\n\n# Direct message by user URI or display name (same --text-file / heredoc rules)\nparall dm prll://usr_xxx --text-file /tmp/reply.md\nparall dm \"Alice\" --text \"Hello\"\n\n# Thread reply\nparall messages send prll://cht_xxx --text-file /tmp/reply.md --thread-root-id 01JWC...\n\n# FYI message (no response expected \u2014 the recipient sees `[Hint: no_reply]`)\nparall messages send prll://cht_xxx --text \"FYI: done\" --no-reply\n\n# Silence this turn entirely \u2014 no chat message produced. Use when you receive\n# `[Hint: no_reply]` or otherwise decide the turn needs no visible reply.\n# Run BEFORE any `messages send` / `dm`; those still deliver real messages.\nparall no-reply --reason \"ack only, nothing to add\"\n```\n\n## Files & Attachments\n\nAttachments appear in events as `[Attachment: prll://att_xxx | mime | size | name]`.\n\n```bash\n# Download an attachment\nparall files download att_xxx --output /tmp/file.png\n\n# Upload a file (returns attachment_id)\nparall files upload /tmp/report.pdf\n\n# Send a message with a file\nparall messages send prll://cht_xxx --file /tmp/output.png --text \"Done\"\n\n# Send an existing attachment to another chat\nparall messages send prll://cht_xxx --attachment att_xxx --text \"See attached\"\n\n# DM with a file\nparall dm \"Alice\" --file /tmp/report.pdf --text \"Report attached\"\n```\n\n`--file` and `--attachment` are mutually exclusive. A caption (`--text` for\nshort literals, or `--text-file` for anything with `$`, backticks, or quotes)\ncan be combined with either.\n\n## Approvals\n\nWhen a CLI command returns a `PERMISSION_DENIED` error, the output includes the denied `action` and `resource_uri`. Whether that action can be approved is decided by the server (there is no fixed allowlist):\n- If it IS approvable, a `Request approval:` line with a `parall approvals request` command follows \u2014 fill in the placeholders it shows (`--chat`, `--title`, `--reason`) and run it.\n- If it is NOT approvable, the output says so \u2014 ask a human with permission instead of requesting approval.\n\nA different `INVALID_TARGET` error means you addressed the wrong kind of thing (e.g. a `usr_` id where a chat is expected). Follow the message (e.g. use `parall dm` to message a user) \u2014 do not request approval for it.\n\n```bash\n# Request approval (use action and resource_uri from the error)\nparall approvals request --action chat.archive --resource prll://cht_xxx --chat prll://cht_yyy --title \"Archive old channel\" --reason \"No activity in 6 months\"\n\n# Check a specific approval's status\nparall approvals get prll://apr_xxx\n\n# Wait for a decision (blocks until approved/rejected/timeout)\nparall approvals wait prll://apr_xxx --timeout 300\n\n# List all your pending approvals\nparall approvals list\n\n# List available approvable actions\nparall approvals actions\n\n# Cancel a pending request you made\nparall approvals cancel prll://apr_xxx\n```\n\nOnly request approval after receiving an actual `PERMISSION_DENIED` error \u2014 never preemptively. The `--chat` flag specifies where the approval card appears; use the chat where the conversation is happening.\n\n## Reference URIs\n\nEvery entity is addressable with a `prll://` URI. Common prefixes you'll see in events, messages, and schedule descriptions:\n\n| Prefix | Entity | Skill |\n|--------|--------|-------|\n| `prll://usr_` | User (human or agent) | parall-platform |\n| `prll://cht_` | Chat | parall-platform |\n| `prll://msg_` | Message | parall-platform |\n| `prll://cmt_` | Comment (on tasks, wiki pages, changesets) | by target: task comment \u2192 parall-tasks, wiki/changeset comment \u2192 parall-wiki |\n| `prll://ase_` | Agent session | parall-platform |\n| `prll://tsk_` | Task | parall-tasks |\n| `prll://prj_` | Project | parall-tasks |\n| `prll://sch_` | Schedule (time trigger) | parall-schedules |\n| `prll://srn_` | Schedule run (single fire audit record; carries fire-time snapshot) | parall-schedules |\n| `prll://xcn_` | External Trigger Connection (incoming endpoint) | parall-external-triggers |\n| `prll://xin_` | External Trigger Event (single incoming event audit record) | parall-external-triggers |\n| `prll://xtr_` | External Trigger (incoming trigger configuration) | parall-external-triggers |\n| `prll://xrn_` | External Trigger run (single matched dispatch audit record) | parall-external-triggers |\n| `prll://wik_` | Wiki | parall-wiki |\n| `prll://att_` | Attachment | parall-platform (files) |\n\nWhen a message or event references `prll://sch_xxx` or `prll://srn_xxx`, or when you receive `[Event: schedule.fired]`, switch to the **parall-schedules** skill for the CLI commands (create / list / pause / resume / cancel / runs).\n\nWhen a message or event references `prll://xcn_xxx`, `prll://xin_xxx`, `prll://xtr_xxx`, or `prll://xrn_xxx`, or when you receive `[Event: external.trigger]`, switch to the **parall-external-triggers** skill for the CLI commands (connections / triggers / events / runs).\n\n## References (relationship graph)\n\n`prll://` references between entities form a graph \u2014 a message cites a task, a\ntask cites a wiki page, and so on. Walk it to answer \"what is this decision /\nentity connected to\". All results are permission-filtered to what you can see.\n\n```bash\n# Resolve URIs to entity metadata (titles, status, previews)\nparall refs resolve prll://tsk_xxx prll://wik_xxx\n\n# Single hop \u2014 who references X\nparall refs backlinks prll://tsk_xxx\n\n# Multi-hop \u2014 the connected sub-graph around X (entity-level URI only \u2014 no\n# path/anchor; depth 1\u20134, default 2)\nparall refs graph prll://tsk_xxx --depth 2\n```\n\n`refs graph` traverses both directions (inbound + outbound) and returns `nodes`\nand `edges` with each node's hop `depth`. `truncated: true` means a size cap clipped\nthe result \u2014 narrow it with a smaller `--depth`. Edges carry `context` \u2014 the\nauthor's annotation from `[context](prll://...)` \u2014 telling you *why* two\nentities are linked, not just that they are.\n\nThe graph returns bare node URIs (no titles). The usual two-step: `refs graph`\nfor topology, then batch-`refs resolve` the node URIs you care about for\ntitles/status. If graph rejects your URI with a path/anchor error, strip it to\nthe entity root (`prll://wik_xxx/docs/a.md` \u2192 `prll://wik_xxx`) and re-query \u2014\nbut note this WIDENS the query to the whole entity, not that one file: the\ngraph seeds from the wiki id, so a specific file's outbound links may sit\ndeeper in the result (or past the size caps). For refs pointing AT one file\n(inbound), `refs backlinks` on the full file URI is precise. There is no\nprecise query for one file's OUTBOUND edges today \u2014 the widened root graph is\nbest-effort for those, or read the file itself for its `prll://` links.\nWiki-file nodes inside a graph *result* do legitimately carry paths.\n\n`refs backlinks` items include a `snippet` of the referencing content \u2014 often\nenough to judge relevance without fetching the source entity.\n\nCLI success output is JSON. Errors print a JSON line (`{\"error\",\"status\",\"code\",...}`) and, on a `PERMISSION_DENIED`, may add a plain-text `Request approval:` line \u2014 read both.\n";
 //# sourceMappingURL=parall-platform.d.ts.map

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

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

package/dist/skills/parall-platform.js

@@ -76,11 +76,11 @@ settled questions or repeat known mistakes. This searches live org data
 can see.
 
 \`\`\`bash
-# Semantic + keyword search across messages, tasks, and wiki
+# Semantic + keyword search across messages, tasks, wiki, and comments
 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).
+# Restrict entity types (m=message, t=task, w=wiki, c=comment). --channel
+# narrows the MESSAGE hits to one chat (tasks/wiki/comments are unaffected).
 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;
@@ -201,6 +201,8 @@ Every entity is addressable with a \`prll://\` URI. Common prefixes you'll see i
 | \`prll://usr_\` | User (human or agent) | parall-platform |
 | \`prll://cht_\` | Chat | parall-platform |
 | \`prll://msg_\` | Message | parall-platform |
+| \`prll://cmt_\` | Comment (on tasks, wiki pages, changesets) | by target: task comment → parall-tasks, wiki/changeset comment → parall-wiki |
+| \`prll://ase_\` | Agent session | parall-platform |
 | \`prll://tsk_\` | Task | parall-tasks |
 | \`prll://prj_\` | Project | parall-tasks |
 | \`prll://sch_\` | Schedule (time trigger) | parall-schedules |
@@ -236,7 +238,24 @@ 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\`.
+the result — narrow it with a smaller \`--depth\`. Edges carry \`context\` — the
+author's annotation from \`[context](prll://...)\` — telling you *why* two
+entities are linked, not just that they are.
+
+The graph returns bare node URIs (no titles). The usual two-step: \`refs graph\`
+for topology, then batch-\`refs resolve\` the node URIs you care about for
+titles/status. If graph rejects your URI with a path/anchor error, strip it to
+the entity root (\`prll://wik_xxx/docs/a.md\` → \`prll://wik_xxx\`) and re-query —
+but note this WIDENS the query to the whole entity, not that one file: the
+graph seeds from the wiki id, so a specific file's outbound links may sit
+deeper in the result (or past the size caps). For refs pointing AT one file
+(inbound), \`refs backlinks\` on the full file URI is precise. There is no
+precise query for one file's OUTBOUND edges today — the widened root graph is
+best-effort for those, or read the file itself for its \`prll://\` links.
+Wiki-file nodes inside a graph *result* do legitimately carry paths.
+
+\`refs backlinks\` items include a \`snippet\` of the referencing content — often
+enough to judge relevance without fetching the source entity.
 
 CLI success output is JSON. Errors print a JSON line (\`{"error","status","code",...}\`) and, on a \`PERMISSION_DENIED\`, may add a plain-text \`Request approval:\` line — read both.
 `;

package/dist/types.d.ts

@@ -63,10 +63,14 @@ export type ParallEvent = {
     /** External IM channel metadata, used for channel_message events. */
     channelProvider?: string;
     channelConversationType?: string;
-    /** Provider-side conversation id (the send_message target). */
+    /** Provider-side conversation id (the reply's addressing target). */
     channelExternalConversationId?: string;
     /** Provider-side message id (in-thread reply target). */
     channelExternalMessageId?: string;
+    /** Live capability grant: the `<provider>-cli` capability is active, so
+     *  the vendor CLI (broker shim) is on PATH and is THE reply path. False /
+     *  absent → outbound is disabled for this org; the hint says so. */
+    channelCliCapable?: boolean;
     /** Original event timestamp (e.g., message.created_at). When present,
      *  input steps use this instead of server insertion time for ordering. */
     sentAt?: string;

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.42.0",
+  "version": "1.43.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.42.0"
+    "@parall/sdk": "1.43.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/bin/channel-exec.ts

@@ -0,0 +1,262 @@
+// channel-exec — the short-lived exec form of the channel-capability
+// credential engine. Invoked by the pointer shims the materializer drops on
+// the capability PATH (e.g. `lark-cli` → `node <this file> --channel feishu
+// --bin lark-cli --skip-dir <shimDir> -- <args…>`): mints a fresh short-lived
+// token from the platform on EVERY call, injects it as the vendor CLI's own
+// documented env credentials, resolves the real binary past the shim
+// directory, and execs it with stdio passthrough.
+//
+// This is a process entry point, not a library — importing it runs main().
+// It lives inside @parall/agent-core so it ships atomically with the bridge
+// (image / daemon bundle), never depending on agent-writable install state.
+// Design: docs/engineering-design/agent-capability-fragments-design.md §5.1.
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { CHANNEL_POINTER_MAGIC } from '../channel-capability.js';
+import { ChannelTokenError, mintChannelToken } from '../channel-token.js';
+
+// The vendor binary each channel targets is fixed HERE, not taken from the
+// caller — channel-exec must never mint a token and hand it to a
+// caller-named program. `--bin` is deliberately not an argument, so a request
+// like `--channel feishu --bin evil` (with a tampered PATH) cannot redirect
+// the minted token to an attacker-chosen executable.
+const CHANNEL_BIN: Record<string, string> = { feishu: 'lark-cli' };
+
+interface ExecArgs {
+  channel: string;
+  skipDir: string;
+  rest: string[];
+}
+
+function fail(prefix: string, msg: string, code: number): never {
+  // Write to fd 2 SYNCHRONOUSLY: process.exit() right after an async
+  // process.stderr.write() can truncate the message when stderr is a pipe
+  // (notably on Windows) — and this path carries the install hint / revocation
+  // message the agent must relay to the user. writeSync flushes before exit;
+  // exit still runs so fail() keeps its `never` contract.
+  try {
+    fs.writeSync(2, `${prefix}: ${msg}\n`);
+  } catch {
+    // best-effort — still exit with the intended status
+  }
+  process.exit(code);
+}
+
+function parseArgs(argv: string[]): ExecArgs {
+  const out: ExecArgs = { channel: '', skipDir: '', rest: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') {
+      out.rest = argv.slice(i + 1);
+      break;
+    }
+    if (a === '--channel') out.channel = argv[++i] ?? '';
+    else if (a === '--skip-dir') out.skipDir = argv[++i] ?? '';
+    else fail('channel-exec', `unknown argument ${a}`, 2);
+  }
+  if (!out.channel) {
+    fail('channel-exec', 'usage: channel-exec --channel <type> [--skip-dir <dir>] -- <args…>', 2);
+  }
+  return out;
+}
+
+// A candidate that carries the pointer magic in its head is one of OUR
+// pointers (or a stray copy of one) — never the real vendor binary. This
+// makes self-recursion structurally impossible even when the skip-dir hint
+// is wrong or the pointer got copied elsewhere on PATH.
+function isCapabilityPointer(candidate: string): boolean {
+  try {
+    const fd = fs.openSync(candidate, 'r');
+    try {
+      const buf = Buffer.alloc(256);
+      const n = fs.readSync(fd, buf, 0, buf.length, 0);
+      return buf.toString('utf8', 0, n).includes(CHANNEL_POINTER_MAGIC);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return false;
+  }
+}
+
+// Resolve the REAL vendor binary along PATH, skipping the shim's own
+// directory (realpath comparison, so symlinked layouts don't fool it).
+function resolveRealBin(bin: string, skipDir: string): string | null {
+  const isWin = process.platform === 'win32';
+  // npm on Windows installs `<bin>` (sh) + `<bin>.cmd` + `<bin>.ps1`; the sh
+  // file is not spawnable by CreateProcess, so prefer the .cmd/.exe forms.
+  const exts = isWin ? ['.cmd', '.exe', '.bat'] : [''];
+  let skipReal: string | null = null;
+  if (skipDir) {
+    try {
+      skipReal = fs.realpathSync(skipDir);
+    } catch {
+      skipReal = null;
+    }
+  }
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    let real: string;
+    try {
+      real = fs.realpathSync(dir);
+    } catch {
+      continue;
+    }
+    if (skipReal && real === skipReal) continue;
+    for (const ext of exts) {
+      const candidate = path.join(dir, bin + ext);
+      try {
+        if (fs.statSync(candidate).isFile() && !isCapabilityPointer(candidate)) return candidate;
+      } catch {
+        // keep scanning
+      }
+    }
+  }
+  return null;
+}
+
+// The exact lark-cli env credentials the broker OWNS: the values it injects
+// plus the ambient auth inputs it must strip so nothing widens the identity
+// beyond the minted grant. Scrubbing is confined to THESE names — never a
+// blanket LARKSUITE_CLI_* wipe — so legitimate operator controls
+// (LARKSUITE_CLI_CONFIG_DIR / LOG_DIR / CONTENT_SAFETY_MODE / …) survive.
+const FEISHU_OWNED_ENV = [
+  // injected (canonical values set below)
+  'LARKSUITE_CLI_APP_ID',
+  'LARKSUITE_CLI_BRAND',
+  'LARKSUITE_CLI_TENANT_ACCESS_TOKEN',
+  'LARKSUITE_CLI_DEFAULT_AS',
+  'LARKSUITE_CLI_STRICT_MODE',
+  // ambient auth bypass inputs that must not reach the child
+  'LARKSUITE_CLI_APP_SECRET',
+  'LARKSUITE_CLI_USER_ACCESS_TOKEN',
+  'LARKSUITE_CLI_AUTH_PROXY',
+  'LARKSUITE_CLI_PROXY_KEY',
+];
+
+// Per-channel env injection: the ONLY channel-specific knowledge in this
+// entry.
+function buildChildEnv(
+  channel: string,
+  minted: { app_id: string; brand: string; token: string },
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  if (channel === 'feishu') {
+    // Delete the broker-owned names case-insensitively: Windows env keys are
+    // case-insensitive and a plain-object spread keeps the host's casing, so
+    // an uppercase-only delete would miss e.g. `Larksuite_Cli_Auth_Proxy` (a
+    // bypass leak) or leave a stale-cased duplicate shadowing the injected
+    // token. Non-owned LARKSUITE_CLI_* operator settings are left untouched.
+    const owned = new Set(FEISHU_OWNED_ENV);
+    for (const key of Object.keys(env)) {
+      if (owned.has(key.toUpperCase())) delete env[key];
+    }
+    env.LARKSUITE_CLI_APP_ID = minted.app_id;
+    env.LARKSUITE_CLI_BRAND = minted.brand || 'feishu';
+    env.LARKSUITE_CLI_TENANT_ACCESS_TOKEN = minted.token;
+    // Bot lock: the credential is the app's, not a human's.
+    env.LARKSUITE_CLI_DEFAULT_AS = 'bot';
+    env.LARKSUITE_CLI_STRICT_MODE = 'bot';
+    return env;
+  }
+  fail('channel-exec', `unsupported channel type "${channel}"`, 2);
+}
+
+// Windows argv-preserving quoting, ported from cross-spawn (the npm-ecosystem
+// standard for correctly launching .cmd shims). Node's `shell: true` does NOT
+// escape arguments — it concatenates them, so JSON/message args split or
+// inject on cmd.exe — and CreateProcess cannot run a .cmd directly. The proven
+// path is cmd.exe /d /s /c with each token escaped for BOTH the CreateProcess
+// argv layer and the cmd.exe metachar layer (double-escaped because a .cmd
+// re-parses). Still Windows-only and NO Windows CI: validate on a real Windows
+// host before the first Windows selfhost user (the round-trip tests lock the
+// escaping rules, not the live cmd.exe behavior).
+// cmd.exe metacharacters, matching cross-spawn's metaCharsRegExp (v7.0.6). ONE
+// set shared by BOTH the command and the arguments — cross-spawn uses a single
+// regex for both, and a split set is a real correctness hole: a metachar
+// caret-escaped in the command path but left bare in an argument (or the
+// reverse) survives only one of cmd.exe's two parse passes. Includes the
+// separators (space, `;`, `,`) and glob chars (`*`, `?`) so a quoted argument's
+// separators are still neutralized for the `.cmd` re-parse, exactly as
+// cross-spawn does.
+const CMD_META_CHARS = /([()\][%!^"`<>&|;, *?])/g;
+
+function escapeCmdArgument(arg: string): string {
+  let out = `${arg}`;
+  // Double backslashes before a quote, and trailing backslashes, then wrap.
+  out = out.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1');
+  out = `"${out}"`;
+  // cmd metachars, escaped twice (the .cmd forwarder re-parses).
+  out = out.replace(CMD_META_CHARS, '^$1').replace(CMD_META_CHARS, '^$1');
+  return out;
+}
+
+function escapeCmdCommand(command: string): string {
+  return command.replace(CMD_META_CHARS, '^$1');
+}
+
+function runReal(realBin: string, args: string[], env: NodeJS.ProcessEnv, prefix: string): never {
+  const isWinScript = process.platform === 'win32' && /\.(cmd|bat)$/i.test(realBin);
+  const result = isWinScript
+    ? spawnSync(
+        process.env.comspec || 'cmd.exe',
+        [
+          '/d',
+          '/s',
+          '/c',
+          `"${[escapeCmdCommand(realBin), ...args.map(escapeCmdArgument)].join(' ')}"`,
+        ],
+        { stdio: 'inherit', env, windowsVerbatimArguments: true },
+      )
+    : spawnSync(realBin, args, { stdio: 'inherit', env });
+  if (result.error) {
+    fail(prefix, `failed to run ${realBin}: ${String(result.error)}`, 1);
+  }
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+    // Unreachable in practice; satisfy the `never` contract if the signal is trapped.
+    process.exit(1);
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+// Exported for round-trip unit tests (Windows spawn can't run in CI).
+export { escapeCmdArgument, escapeCmdCommand };
+
+async function main(): Promise<void> {
+  const { channel, skipDir, rest } = parseArgs(process.argv.slice(2));
+  const bin = CHANNEL_BIN[channel];
+  if (!bin) fail('channel-exec', `unsupported channel type "${channel}"`, 2);
+  const prefix = bin;
+
+  let minted: Awaited<ReturnType<typeof mintChannelToken>>;
+  try {
+    minted = await mintChannelToken(channel, process.env);
+  } catch (err) {
+    if (err instanceof ChannelTokenError) fail(prefix, err.message, 1);
+    fail(prefix, String(err), 1);
+  }
+
+  const real = resolveRealBin(bin, skipDir);
+  if (!real) {
+    const hint =
+      channel === 'feishu'
+        ? 'Install it once with:\n  npm i -g @larksuite/cli && npx skills add larksuite/cli -y -g'
+        : 'Install it and retry.';
+    fail(prefix, `the ${bin} binary is not installed. ${hint}`, 127);
+  }
+
+  runReal(real, rest, buildChildEnv(channel, minted), prefix);
+}
+
+// Run main() only when invoked AS A PROGRAM (the pointer shim runs
+// `node <this>`), not when a test imports this module for the escape helpers.
+// Holds in both layouts: npm (argv[1] = channel-exec.js) and bundle
+// (argv[1] = parall-channel-exec.js, which is also this module's own url).
+const invokedPath = process.argv[1];
+if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
+  void main();
+}