@parall/agent-core 1.42.1 → 1.44.0

package/src/prompt-fragments.ts

@@ -212,10 +212,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:
 
@@ -261,15 +261,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/src/skills/index.ts

@@ -21,7 +21,7 @@ export const SKILLS: SkillMeta[] = [
   {
     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.",
+      "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/src/skills/parall-platform.ts

@@ -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/src/types.ts

@@ -69,10 +69,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;