@parall/agent-core 1.42.1 → 1.43.0

package/src/gateway-base.ts

@@ -148,6 +148,14 @@ export type ParallGatewayOptions = {
    * this directory. Absent → legacy received/ack flow (openclaw / hermes).
    */
   dispatchContextDir?: string;
+  /**
+   * Live view of the agent's platform-granted capability keys (bridges wire
+   * PlatformConfigManager.capabilities().map(c => c.key)). Read at
+   * channel-event build time so the reply hint routes to the capability
+   * affordance (e.g. feishu-cli → lark-cli) — the single outbound path.
+   * Absent/empty → the hint states outbound is disabled.
+   */
+  getCapabilityKeys?: () => string[];
   onConfigUpdate?: (data: AgentConfigUpdateData) => Promise<void> | void;
   onSessionReady?: (state: {
     activeSessionId?: string;
@@ -293,6 +301,9 @@ export class ParallAgentGateway {
   // (stable mapping; avoids one connection fetch per inbound message).
   private readonly channelConnectionProviders = new Map<string, string>();
   private readonly dispatchedMessages = new Set<string>();
+  // Per-WorkItem failure backoff for typed dispatch consumption — see
+  // LaneFlowHost.typedRedriveBackoff in gateway-lane-flow.ts.
+  readonly typedRedriveBackoff = new Map<string, { failures: number; until: number }>();
   private readonly forkStates = new Map<string, ActiveForkState>();
   private readonly dispatchState: DispatchState = {
     mainDispatching: false,
@@ -448,8 +459,17 @@ export class ParallAgentGateway {
                 source_id: data.id,
               })
               .then(
-                () => undefined,
-                () => undefined,
+                () => true,
+                (err) => {
+                  // Same contract as ackDispatchEvent: a failed ack is a
+                  // failed consume (arms backoff) and must free the hot-path
+                  // dedupe so the re-drive isn't rejected by this pod forever.
+                  this.dispatchedTasks.delete(`${data.id}:${data.updated_at}`);
+                  this.opts.log?.warn(
+                    `dispatch ack failed for task ${data.id}, releasing for re-drive: ${String(err)}`,
+                  );
+                  return false;
+                },
               );
           },
         );
@@ -680,17 +700,20 @@ export class ParallAgentGateway {
   private consumeTypedDispatch(
     ref: { dispatchEventId?: string; sourceType?: string; sourceId?: string },
     run: (dispatchEventId?: string) => Promise<boolean>,
-    ack: (dispatchEventId?: string) => void | Promise<void>,
+    ack: (dispatchEventId?: string) => boolean | void | Promise<boolean | void>,
   ): Promise<void> {
     return consumeTypedDispatch(this.laneFlowHost(), ref, run, ack);
   }
 
   // Typed completion must wait until the administrative ack has either
   // committed or failed. Errors stay best-effort: a failed ack leaves the row
-  // received, so Complete releases and re-drives it safely.
-  private ackDispatchEvent(dispatchEventId: string, onFailure?: () => void): Promise<void> {
+  // received, so Complete releases and re-drives it safely. The boolean
+  // outcome feeds the typed-consume backoff — an ack that failed must count
+  // as a failed consume, or an ack outage would clear the backoff entry and
+  // let the release re-drive spin at wire speed.
+  private ackDispatchEvent(dispatchEventId: string, onFailure?: () => void): Promise<boolean> {
     return this.opts.client.ackDispatchByID(this.opts.config.org_id, dispatchEventId).then(
-      () => undefined,
+      () => true,
       (err) => {
         // Complete will return the still-received item to pending and publish
         // an immediate hint. Free its hot-path claim first, otherwise that
@@ -699,6 +722,7 @@ export class ParallAgentGateway {
         this.opts.log?.warn(
           `dispatch ack failed for ${dispatchEventId}, releasing for re-drive: ${String(err)}`,
         );
+        return false;
       },
     );
   }
@@ -2471,6 +2495,19 @@ export class ParallAgentGateway {
       }
     }
 
+    // The reply hint routes on the live capability grant: `<provider>-cli`
+    // present → the vendor CLI is on PATH (broker shim) and is THE reply
+    // path; absent → outbound is disabled for this org (flag/connection off)
+    // and the hint must say so instead of pointing at a retired clip. The
+    // provider label lookup above is best-effort/cosmetic — when it fails,
+    // ANY granted `*-cli` capability keeps the hint on the CLI path: a
+    // transient metadata miss must not flip an actively granted agent's
+    // hint to "outbound disabled" and strand a valid external message.
+    const keys = this.opts.getCapabilityKeys?.() ?? [];
+    const cliCapable = provider
+      ? keys.includes(`${provider}-cli`)
+      : keys.some((k) => k.endsWith('-cli'));
+
     const event: ParallEvent = {
       type: 'channel_message',
       targetId: conv.id,
@@ -2485,6 +2522,7 @@ export class ParallAgentGateway {
       channelConversationType: conv.conversation_type || undefined,
       channelExternalConversationId: conv.external_conversation_id,
       channelExternalMessageId: msg.external_message_id,
+      channelCliCapable: cliCapable,
       ackSourceType: 'channel_message',
       ackSourceId: msg.id,
     };

package/src/gateway-lane-flow.ts

@@ -18,6 +18,15 @@ export interface LaneFlowHost {
   ledgerDisabled: boolean;
   shuttingDown: boolean;
   dispatchedMessages: Set<string>;
+  /**
+   * Per-WorkItem failure backoff for typed dispatch consumption. A consume
+   * that ends without an ack re-arms the entry; the next attempt for the
+   * same WorkItem is delayed (not skipped — a skipped attempt would strand
+   * the pending row until reconnect catch-up) so a claim→fail→complete
+   * tight loop is throttled to exponential intervals instead of spinning at
+   * wire speed against the server's immediate re-drive (2026-07-11 OOM).
+   */
+  typedRedriveBackoff: Map<string, { failures: number; until: number }>;
   opts: {
     client: ParallClient;
     log?: GatewayLogger;
@@ -122,21 +131,91 @@ export async function dispatchLaneGroup(
   return 'dispatched';
 }
 
+/** Failure backoff pacing for typed dispatch retries (base 2s, cap 5min). */
+const TYPED_BACKOFF_BASE_MS = 2_000;
+const TYPED_BACKOFF_CAP_MS = 5 * 60_000;
+const TYPED_BACKOFF_MAP_CAP = 512;
+
 /**
  * Consume one typed dispatch (task/comment/schedule/trigger/approval) under
  * its typed-lane occupancy guard: claim the dsp:<id> lane (skip when another
  * pod holds it or the WorkItem is already resolved), run the handler, ack on
  * success (the doc's option (b): notification delivered, tracked elsewhere),
  * then release the lane. Legacy run+ack flow when the ledger is unavailable.
+ *
+ * Repeated failures back off: a consume that ends un-acked re-arms the
+ * WorkItem's backoff entry, and the next attempt sleeps out the remaining
+ * window before claiming. Without this, complete's release re-drives the
+ * item instantly and a persistently-failing consume (e.g. buffered behind a
+ * saturated fork pool) spins at wire speed — the client half of the
+ * 2026-07-11 poison loop (the server half is the redrive budget).
  */
 export async function consumeTypedDispatch(
   host: LaneFlowHost,
   ref: { dispatchEventId?: string; sourceType?: string; sourceId?: string },
   run: (dispatchEventId?: string) => Promise<boolean>,
-  ack: (dispatchEventId?: string) => void | Promise<void>,
+  ack: (dispatchEventId?: string) => boolean | void | Promise<boolean | void>,
 ): Promise<void> {
+  const backoffKey = ref.dispatchEventId ?? `${ref.sourceType}:${ref.sourceId}`;
+  const armed = host.typedRedriveBackoff.get(backoffKey);
+  if (armed) {
+    const waitMs = armed.until - Date.now();
+    if (waitMs > 0) {
+      host.opts.log?.info(
+        `typed dispatch ${backoffKey} backing off ${Math.ceil(waitMs / 1000)}s after ${armed.failures} failed consume(s)`,
+      );
+      // unref: the wait must never be what keeps the process alive — on
+      // SIGTERM the gateway drains and exits while this timer is pending
+      // (the re-drive/renotify path re-delivers on the next pod).
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(resolve, waitMs);
+        timer.unref?.();
+      });
+    }
+    if (host.shuttingDown) return;
+  }
+  // An ack callback that returns void (legacy custom acks) counts as success;
+  // an explicit false (ackDispatchEvent's failed HTTP ack) is a failed
+  // consume — clearing backoff there would let an ack outage re-create the
+  // wire-speed release/re-drive loop against a pre-budget server.
+  const settleAck = (ackResult: boolean | void) => ackResult !== false;
+  const settle = (acked: boolean) => {
+    if (acked) {
+      host.typedRedriveBackoff.delete(backoffKey);
+      return;
+    }
+    const failures = (host.typedRedriveBackoff.get(backoffKey)?.failures ?? 0) + 1;
+    const backoffMs = Math.min(TYPED_BACKOFF_CAP_MS, TYPED_BACKOFF_BASE_MS * 2 ** (failures - 1));
+    // True LRU: delete-then-set moves an updated key to the tail of the
+    // Map's insertion order, so capacity eviction always removes the
+    // least-recently-FAILING key — an actively-failing old key must not be
+    // evicted ahead of a quieter newer one. Evict only when inserting a new
+    // key at capacity (an in-place update never shrinks the map).
+    if (
+      host.typedRedriveBackoff.delete(backoffKey) === false &&
+      host.typedRedriveBackoff.size >= TYPED_BACKOFF_MAP_CAP
+    ) {
+      const oldest = host.typedRedriveBackoff.keys().next().value;
+      if (oldest !== undefined) host.typedRedriveBackoff.delete(oldest);
+    }
+    host.typedRedriveBackoff.set(backoffKey, { failures, until: Date.now() + backoffMs });
+  };
+
+  // Legacy run+ack (no ledger): same settle-in-finally contract as the lane
+  // path — a thrown run/ack must arm backoff, not skip it.
+  const runLegacy = async () => {
+    let acked = false;
+    try {
+      if (await run(ref.dispatchEventId)) {
+        acked = settleAck(await ack(ref.dispatchEventId));
+      }
+    } finally {
+      settle(acked);
+    }
+  };
+
   if (!host.laneLedger || host.ledgerDisabled) {
-    if (await run(ref.dispatchEventId)) await ack(ref.dispatchEventId);
+    await runLegacy();
     return;
   }
   let lane: Awaited<ReturnType<LaneLedger['claimTyped']>>;
@@ -145,23 +224,29 @@ export async function consumeTypedDispatch(
   } catch (err) {
     if (err instanceof LedgerUnsupportedError) {
       host.disableLedger('claim endpoint missing');
-      if (await run(ref.dispatchEventId)) await ack(ref.dispatchEventId);
+      await runLegacy();
       return;
     }
     throw err;
   }
   if (!lane) {
+    // Held elsewhere or already resolved — not a local failure; leave the
+    // backoff state as-is (a stale entry is cleared by the next local ack).
     host.opts.log?.info(
       `typed dispatch ${ref.dispatchEventId ?? `${ref.sourceType}:${ref.sourceId}`} not claimable (held elsewhere or already resolved) — skipping`,
     );
     return;
   }
+  let acked = false;
   try {
     // Ack must settle before Complete. A fire-and-forget ack races the lane
     // release: Complete can return the still-received typed item to pending
     // and publish a re-drive while its successful ack is still in flight.
-    if (await run(lane.typedDispatchEventId)) await ack(lane.typedDispatchEventId);
+    if (await run(lane.typedDispatchEventId)) {
+      acked = settleAck(await ack(lane.typedDispatchEventId));
+    }
   } finally {
+    settle(acked);
     // Release the occupancy row. A buffered dispatch may outlive this guard
     // (lane TTL) — acceptable at-least-once; the ledger's resolution paths
     // still dedupe the persistent side effects.

package/src/index.ts

@@ -2,6 +2,7 @@ export * from './provider-config.js';
 export * from './types.js';
 export * from './lane-key.js';
 export type { LaneFlowHost } from './gateway-lane-flow.js';
+export { consumeTypedDispatch } from './gateway-lane-flow.js';
 export * from './session-state.js';
 export * from './routing.js';
 export * from './event-format.js';
@@ -11,6 +12,8 @@ export * from './dispatch-adapter.js';
 export { createLogger, childLogger } from './logger.js';
 export * from './gateway-base.js';
 export * from './platform-config.js';
+export * from './channel-capability.js';
+export * from './channel-token.js';
 export { writeSkillFiles, buildSkillReferences, SKILLS } from './skills/index.js';
 export type { SkillMeta } from './skills/index.js';
 export {

package/src/platform-config.ts

@@ -17,6 +17,46 @@ export interface PlatformConfigManager {
   fetch(): Promise<PlatformDefaults>;
   current(): PlatformDefaults;
   rawConfig(): Record<string, unknown> | null;
+  /**
+   * Channel capabilities delivered in `agents.capabilities[]` — the
+   * declaration plane of the channel-capability broker. Reads the current
+   * (possibly LKG-cached) config with NO freshness gate: the credential is
+   * pull-at-use (the mint endpoint re-evaluates the grant on every call), so
+   * a stale declaration fail-closes there with a self-explanatory 403 — like
+   * a stale model, it is suboptimal, never dangerous.
+   */
+  capabilities(): AgentCapability[];
+}
+
+// One platform-granted capability (agents.capabilities[] in platform-config).
+// `fragment` is the complete system-prompt declaration text; the server is
+// the SSOT for channel knowledge, runtimes just splice it in.
+export interface AgentCapability {
+  key: string;
+  source: string;
+  fragment: string;
+}
+
+// Defensive extraction: entries missing a non-empty string key/fragment are
+// skipped so a malformed or future-shaped payload can never inject a blank
+// declaration into a system prompt.
+export function extractCapabilities(config: Record<string, unknown>): AgentCapability[] {
+  const agents = (config.agents ?? {}) as Record<string, unknown>;
+  const raw = agents.capabilities;
+  if (!Array.isArray(raw)) return [];
+  const out: AgentCapability[] = [];
+  for (const entry of raw) {
+    if (typeof entry !== 'object' || entry === null) continue;
+    const e = entry as Record<string, unknown>;
+    if (typeof e.key !== 'string' || !e.key) continue;
+    if (typeof e.fragment !== 'string' || !e.fragment) continue;
+    out.push({
+      key: e.key,
+      source: typeof e.source === 'string' ? e.source : '',
+      fragment: e.fragment,
+    });
+  }
+  return out;
 }
 
 export interface PlatformManagementProfile {
@@ -276,5 +316,9 @@ export function createPlatformConfigManager(opts: {
     rawConfig(): Record<string, unknown> | null {
       return currentRawConfig;
     },
+
+    capabilities(): AgentCapability[] {
+      return currentRawConfig ? extractCapabilities(currentRawConfig) : [];
+    },
   };
 }

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;