Skip to content

feat(agentMentionService): inline cross-runtime consultation cue - #416

Closed
samxu01 wants to merge 1 commit into
mainfrom
feat/cross-runtime-consult-inline-cue
Closed

feat(agentMentionService): inline cross-runtime consultation cue#416
samxu01 wants to merge 1 commit into
mainfrom
feat/cross-runtime-consult-inline-cue

Conversation

@samxu01

@samxu01 samxu01 commented May 21, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds a tight inline cue to every chat.mention payload.content that surfaces the cross-runtime consultation path to non-specialist agents. Pattern follows the reinforced "inline-cue beats structured metadata" rule (ADR-012 §9 + the pod-context-cue precedent).

The cue

[Collaboration: for code-heavy work (writing/debugging/refactoring/repo ops)
 you can consult a coding specialist via 1:1 DM. Call
 commonly_open_dm({ agentName: "codex" }) — returns a podId — then
 commonly_post_message(podId, question). Works when the specialist
 is already a peer in one of your shared pods. Skip for non-code asks.]

Why

Smoke 2026-05-20 cycle 2: Pixel refused a real task with "the local exec tool is unavailable in this session" — capability denial, not infrastructure missing. The commonly_open_dm tool already exists in the openclaw extension; agents just didn't know to reach for it. Without an inline cue, openclaw moltbots either deny capability or struggle alone. Openclaw agents stay first-class — they just now know when to phone a friend.

Target gating

The cue is omitted when the target IS a code specialist (codex / cloud-codex / claude-code). Telling Cody to consult codex is noise and risks self-DM loops. All other agent types (openclaw moltbots, commonly-bot, webhook agents, ad-hoc community agents) get the cue.

Applied at all 3 enqueueMentions enqueue paths:

  1. Direct match
  2. agentName fallback
  3. mention-autoJoin

Token cost

~70 tokens per non-specialist mention. Acceptable trade against silent under-use of cross-runtime collab.

Test plan

  • 3 new tests in agentMentionService.test.js:
    • openclaw target → both pod-context AND consultation cues present
    • codex target → pod-context present, consultation cue OMITTED
    • claude-code target → same gating as codex
  • CI green
  • Manual smoke: post @nova task in a pod where she shares membership with Cody; check her session shows the cue inline; see if she actually uses commonly_open_dm for code work

🤖 Generated with Claude Code

@samxu01
feat(agentMentionService): inline cross-runtime consultation cue
fc59f71 
Follows the reinforced "inline-cue beats structured metadata" pattern
(ADR-012 §9 + pod-context-cue precedent). Prepends a tight cue to
chat.mention payload.content that tells openclaw agents how to consult
a code-heavy specialist via 1:1 DM:

  [Collaboration: for code-heavy work (writing/debugging/refactoring/
   repo ops) you can consult a coding specialist via 1:1 DM. Call
   commonly_open_dm({ agentName: "codex" }) — returns a podId — then
   commonly_post_message(podId, question). Works when the specialist
   is already a peer in one of your shared pods. Skip for non-code asks.]

Why: smoke 2026-05-20 cycle 2 showed Pixel refusing a sheet task with
"the local exec tool is unavailable in this session" — capability
denial, not infra missing. Openclaw agents stay first-class for
routine work, but the heavy-coding runtime lives on cloud-codex /
claude-code adapters. Without an inline cue surfacing this option,
agents either deny capability or struggle alone.

Target-runtime aware via `isCodeSpecialistAgent` guard:
  codex / cloud-codex / claude-code  → cue OMITTED (recursive consult
  is noise + risks self-DM loop formation).
  Everything else (openclaw moltbots, commonly-bot, webhook agents,
  ad-hoc community agents) → cue PRESENT.

Applied at all three enqueue paths in enqueueMentions (direct match,
agentName fallback, mention-autoJoin).

Three regression tests in agentMentionService.test.js cover:
  - openclaw target gets both pod-context + consultation cue
  - codex target gets pod-context but NOT consultation cue
  - claude-code target same gating as codex

Token cost: ~70/mention. Tradeoff is acceptable; the alternative is
silent under-use of cross-runtime collab (Pixel cycle-2 evidence).
samxu01 added a commit that referenced this pull request May 21, 2026
@samxu01
feat(agentMentionService): inline reply-mechanics cue (heartbeat-clob…
7312a54 
…ber mitigation)

Smoke 2026-05-20 produced 3 reproductions of the openclaw heartbeat-clobbers-mention bug (Nova c3, Pixel c7, Ops c7): when an agent processes a chat.mention AND a heartbeat trigger fires in the same model session before the mention reply is committed, the openclaw run-loop's final-turn auto-post emits HEARTBEAT_OK (the LAST assistant turn) and CLOBBERS the in-flight mention answer.

Upstream fix in the openclaw fork is a larger change. This inline cue is the kernel-side mitigation: tell the model NOT to rely on the implicit final-turn auto-post; instead, EXPLICITLY call commonly_post_message as soon as the mention answer is ready. Once committed via tool call, any subsequent heartbeat trigger is harmless.

Cue added ONLY to chat.mention events — thread.mention replies post via a different path on the openclaw side, so the cue would be noise there.

Follows the inline-cue manifest pattern (ADR-012 §9 + pod-context cue precedent). ~340 chars / ~80 tokens. Tradeoff is acceptable against silent-loss of mention replies.

Note: textually overlaps with PR #416 (cross-runtime consultation cue, same function file). Merge order matters; whichever lands second needs a small rebase to compose both cues.
This was referenced May 21, 2026
Closed
Closed
Closed
Merged
@samxu01

samxu01 commented May 21, 2026

Copy link
Copy Markdown
Contributor Author

Superseded by PR #420 (unified inline cue composition). #420 incorporates this consultation cue + #417's reply-mechanics cue with proper per-event-type gating (was a real issue in this PR's standalone form — thread.mention erroneously got the consultation cue). Closing.

@samxu01 samxu01 closed this May 21, 2026
samxu01 added a commit that referenced this pull request May 22, 2026
@samxu01 Sam Xu
feat(agentMentionService): unified inline cue composition (supersedes #…
158d81b 
…416 + #417)

Per code-review feedback on PR #416 + #417: those two PRs touch the
same content-build expression in enqueueMentions and have a mechanical
merge conflict — whichever lands second hits it. Plus #416 didn't gate
on eventType, so thread.mention events got the consultation cue
erroneously.

This PR composes both cues in one place with the correct 4-way matrix:

  chat.mention + non-specialist  → [Pod] [Collab] [Reply] body
  chat.mention + specialist      → [Pod] [Reply] body
  thread.mention + non-specialist→ [Pod] [Collab] body
  thread.mention + specialist    → [Pod] body

Rules:
- Pod-context cue: ALWAYS (existing behavior, untouched)
- Consultation cue: WHEN target agent is NOT a code specialist
  (codex / cloud-codex / claude-code). Both chat.mention AND
  thread.mention paths — code-help is a useful affordance in either
  context.
- Reply-mechanics cue: ONLY for chat.mention. thread.mention replies
  post via a different openclaw path and don't have the heartbeat-
  clobber race shape.

New helper: buildContentForTarget(podId, rawContent, eventType,
targetAgentName) — single place to extend the cue composition in
future iterations. Applied at all 3 enqueue paths (direct-match,
agentName fallback, mention-autoJoin).

Tests cover all 5 combinations (4 from the matrix + claude-code
parity check for specialist gating).

Closes #416 and #417 — both supersede here.

Also incorporates reviewer's suggestion to soften the 403 case in
the consultation cue: 'if you get a 403, they're not [a peer] —
skip', so agents don't silently fail when a specialist isn't in any
shared pod.
samxu01 added a commit that referenced this pull request May 22, 2026
@samxu01
feat(agentMentionService): unified inline cue composition (supersedes #…
ffb0a83 
…416 + #417) (#420)

Per code-review feedback on PR #416 + #417: those two PRs touch the
same content-build expression in enqueueMentions and have a mechanical
merge conflict — whichever lands second hits it. Plus #416 didn't gate
on eventType, so thread.mention events got the consultation cue
erroneously.

This PR composes both cues in one place with the correct 4-way matrix:

  chat.mention + non-specialist  → [Pod] [Collab] [Reply] body
  chat.mention + specialist      → [Pod] [Reply] body
  thread.mention + non-specialist→ [Pod] [Collab] body
  thread.mention + specialist    → [Pod] body

Rules:
- Pod-context cue: ALWAYS (existing behavior, untouched)
- Consultation cue: WHEN target agent is NOT a code specialist
  (codex / cloud-codex / claude-code). Both chat.mention AND
  thread.mention paths — code-help is a useful affordance in either
  context.
- Reply-mechanics cue: ONLY for chat.mention. thread.mention replies
  post via a different openclaw path and don't have the heartbeat-
  clobber race shape.

New helper: buildContentForTarget(podId, rawContent, eventType,
targetAgentName) — single place to extend the cue composition in
future iterations. Applied at all 3 enqueue paths (direct-match,
agentName fallback, mention-autoJoin).

Tests cover all 5 combinations (4 from the matrix + claude-code
parity check for specialist gating).

Closes #416 and #417 — both supersede here.

Also incorporates reviewer's suggestion to soften the 403 case in
the consultation cue: 'if you get a 403, they're not [a peer] —
skip', so agents don't silently fail when a specialist isn't in any
shared pod.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@samxu01