Expose chat.inject metadata for plugin approval updates by Guardiola31337 · Pull Request #82471 · openclaw/openclaw

Guardiola31337 · 2026-05-16T06:06:11Z

Review context

Concrete plugin: Guardiola31337/openclaw-agentkit. The intent is to keep World ID / AgentKit out of OpenClaw core while letting external HITL plugins use the existing approval flow end-to-end.

This PR's role: durable chat/status delivery with metadata and idempotency so external approval cards survive history/live events.

Bundle:

#82431 exposes approval action metadata/UI rendering.
#82434 adds verified approval resolution with plugin ownership checks.
#82471 adds chat/status metadata and idempotency for durable approval updates.

sequenceDiagram
  participant Agent
  participant Gateway
  participant Plugin as HITL plugin
  participant UI as TUI/Web UI
  participant Verifier as External verifier

  Agent->>Gateway: protected tool call
  Gateway->>Plugin: approval hook/request
  Gateway->>UI: approval card + plugin actions
  UI->>Plugin: user chooses verify once / trust session / deny
  Plugin->>Verifier: external proof flow
  Verifier-->>Plugin: verified result
  Plugin->>Gateway: resolve verified approval
  Gateway->>Agent: allow/deny blocked tool
  Plugin->>UI: status/update messages with idempotency

flowchart LR
  A["Approval action surface<br/>#82431"] --> B["Verified resolver<br/>#82434"]
  B --> C["Status/chat idempotency<br/>#82471"]
  C --> D["Usable external HITL plugin flow"]

Trust boundary to review: should a plugin that already owns a pending approval be allowed to complete that specific approval after external verification, through a typed SDK/Gateway path with admin scope and ownership checks?

Summary

Let operator-admin chat.inject accept optional idempotencyKey, command, interactive, and channelData fields.
Persist and broadcast those fields on injected assistant transcript messages so plugin approval/status cards survive chat.history and live chat events.
Enforce idempotencyKey replay at the serialized transcript append boundary so concurrent retries do not append or broadcast duplicate approval cards.
Expose a narrow injectChatMessageOverGateway helper through openclaw/plugin-sdk/gateway-runtime so external plugins do not need a generic admin Gateway client.
Refresh the generated protocol/API surfaces, document the metadata contract, and add live loopback Gateway proof for WebSocket broadcast plus chat.history persistence.

Verification

pnpm protocol:check
pnpm plugin-sdk:api:check
pnpm build:plugin-sdk:strict-smoke
pnpm docs:list
node_modules/.bin/oxfmt --check src/config/sessions/transcript-append.ts src/gateway/server-methods/chat.ts src/gateway/server-methods/chat-transcript-inject.ts src/gateway/server-methods/chat.inject.parentid.test.ts src/gateway/server-methods/chat.directive-tags.test.ts src/gateway/operator-chat-client.ts src/gateway/operator-chat-client.test.ts src/plugin-sdk/gateway-runtime.ts src/gateway/client-callsites.guard.test.ts src/gateway/gateway.test.ts docs/gateway/protocol.md docs/plugins/sdk-migration.md docs/plugins/sdk-subpaths.md
node scripts/run-vitest.mjs src/gateway/operator-chat-client.test.ts src/gateway/client-callsites.guard.test.ts --testTimeout 120000 --reporter dot
node scripts/run-vitest.mjs src/gateway/operator-chat-client.test.ts src/gateway/client-callsites.guard.test.ts src/gateway/server-methods/chat.directive-tags.test.ts src/gateway/server-methods/chat.inject.parentid.test.ts src/gateway/server-methods/server-methods.test.ts --testTimeout 120000 --reporter dot
node scripts/run-vitest.mjs src/gateway/gateway.test.ts --testNamePattern "preserves chat.inject metadata through live ws broadcast and chat.history" --testTimeout 120000 --reporter verbose
git diff --check

Real behavior proof

Behavior addressed: chat.inject can carry AgentKit-style approval/status metadata (idempotencyKey, command, interactive, channelData) through Gateway validation, transcript append, live WebSocket chat broadcast, and chat.history, while same-key retries dedupe before any second append or live broadcast. External plugins can use the new narrow SDK helper instead of a generic admin Gateway client.

Real environment tested: local OpenClaw checkout on macOS on May 16, 2026, with a real loopback Gateway server started from the test harness, token auth enabled, one admin WebSocket client issuing RPCs, and one separate watcher WebSocket client receiving live events.

Exact steps or command run after this patch: started the loopback Gateway, created a dashboard session through sessions.create, sent chat.inject with AgentKit-shaped interactive and channelData, replayed the same request with the same idempotencyKey, asserted the second response was { ok: true, deduped: true }, asserted the watcher saw exactly one live chat event carrying the metadata, queried chat.history, and asserted the persisted history message carried the same metadata.

Evidence after fix:

$ node scripts/run-vitest.mjs src/gateway/gateway.test.ts --testNamePattern "preserves chat.inject metadata through live ws broadcast and chat.history" --testTimeout 120000 --reporter verbose
✓ |gateway-client| ../../src/gateway/gateway.test.ts > gateway e2e > preserves chat.inject metadata through live ws broadcast and chat.history 887ms

Test Files  1 passed (1)
Tests  1 passed | 4 skipped (5)

Additional focused proof:

$ node scripts/run-vitest.mjs src/gateway/operator-chat-client.test.ts src/gateway/client-callsites.guard.test.ts --testTimeout 120000 --reporter dot
Test Files  4 passed (4)
Tests  16 passed (16)

$ node scripts/run-vitest.mjs src/gateway/operator-chat-client.test.ts src/gateway/client-callsites.guard.test.ts src/gateway/server-methods/chat.directive-tags.test.ts src/gateway/server-methods/chat.inject.parentid.test.ts src/gateway/server-methods/server-methods.test.ts --testTimeout 120000 --reporter dot
Test Files  9 passed (9)
Tests  271 passed (271)

$ pnpm plugin-sdk:api:check
OK docs/.generated/plugin-sdk-api-baseline.sha256

$ pnpm build:plugin-sdk:strict-smoke
(exit 0)

$ node_modules/.bin/oxfmt --check src/gateway/gateway.test.ts
All matched files use the correct format.

$ git diff --check
(no output)

Observed result after fix: live Gateway behavior now demonstrates the end-to-end host seam this PR owns: metadata-bearing plugin approval/status cards are accepted over the admin RPC, delivered once over WebSocket, durable through chat.history, and safely idempotent on retry. The public plugin SDK exposes a focused injectChatMessageOverGateway helper for external ClawHub plugins to call this path.

What was not tested: full release suite and live World ID credential verification against production AgentKit services; this PR verifies the generic OpenClaw host API contract that the external ClawHub plugin needs. The full AgentKit HITL stack also depends on #82431 for plugin approval action/no-route pending metadata and #82434 for plugin-owned verified approval resolution.

Refs #82336.

External plugin integration proof

Behavior addressed: the external ClawHub AgentKit plugin can consume the combined temporary OpenClaw host API branch that includes this PR's durable chat.inject metadata and narrow chat injection helper.

Real environment tested: GitHub Actions in Guardiola31337/openclaw-agentkit on May 16, 2026, checking out Guardiola31337/openclaw@agentkit/external-plugin-host-apis and linking it into the external plugin package.

Exact steps or command run after this patch: the remote workflow checked out the temporary OpenClaw host branch, installed with frozen lockfiles, ran pnpm build gatewayWatch, ran pnpm build:plugin-sdk:strict-smoke, linked the host checkout into the AgentKit plugin, then ran pnpm test:hitl and pnpm pack:check.

Evidence after fix:

$ gh run watch 25972624778 --repo Guardiola31337/openclaw-agentkit --exit-status
✓ main CI · 25972624778
✓ build in 1m46s
  ✓ Run pnpm build gatewayWatch
  ✓ Run pnpm build:plugin-sdk:strict-smoke
  ✓ Run pnpm dev:link-openclaw .openclaw-source
  ✓ Run pnpm test:hitl
  ✓ Run pnpm pack:check

Observed result after fix: the external plugin builds against the split OpenClaw host APIs, uses the narrow injectChatMessageOverGateway helper instead of a generic admin client, the AgentKit HITL proof passes, and the package dry-run includes the expected ClawHub plugin artifact.

What was not tested: production World ID credential verification. This remote proof exercises the integrated temporary host branch because the external plugin requires this PR together with #82431 and #82434 for the full HITL path.

clawsweeper · 2026-05-16T06:10:16Z

Codex review: needs maintainer review before merge. Reviewed May 27, 2026, 11:15 AM ET / 15:15 UTC.

Summary
The branch adds optional chat.inject metadata/idempotency, persists and broadcasts it through transcript/history/live chat paths, exports a narrow plugin SDK helper, updates generated/docs surfaces, and adds focused Gateway tests.

PR surface: Source +247, Tests +545, Docs 0, Other +16. Total +808 across 16 files.

Reproducibility: not applicable. as a bug reproduction: this is a feature/API PR. The PR body provides after-fix loopback Gateway proof for metadata persistence, live broadcast, history, and dedupe behavior.

Review metrics: 3 noteworthy metrics.

Gateway API additions: 4 optional chat.inject params added. This changes the operator-admin wire contract and needs maintainer approval even though the fields are additive.
Plugin SDK additions: 1 helper and 2 exported types added. The plugin-sdk/gateway-runtime subpath is a third-party plugin contract, so the helper name and authority boundary matter before merge.
Generated client surface: 4 Swift ChatInjectParams fields added. Generated client model changes can create source-compatibility work even when the protocol schema is wire-compatible.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Get maintainer approval for the Gateway/plugin SDK contract together with the companion approval PRs.
Clear or explain the failing check-guards CI result on the latest head.

Risk before merge

The PR deliberately expands public Gateway protocol, plugin SDK, and generated Swift client surfaces, so maintainers need to accept the permanent compatibility shape before merge.
The new path persists and rebroadcasts arbitrary interactive and channelData metadata from an admin-scoped caller, so the approval/UI trust boundary needs explicit maintainer acceptance.
The full external HITL workflow depends on the companion approval APIs; the verified resolver PR at feat: add external plugin approval verification #82434 is still open.
Latest public check-runs for head 1a237ecf76ec1f710a64d1eb5ffbcecc51642747 show check-guards failing, so CI needs inspection or rerun before merge.

Maintainer options:

Clear CI and approve the API contract (recommended)
Before merge, maintainers should clear the failing guard check and explicitly accept the public chat.inject/SDK/generated-client shape together with the companion approval PRs.
Request generated-client compatibility proof
Maintainers can ask for focused OpenClawKit/Swift and plugin SDK consumer proof if source compatibility is a concern despite the additive wire schema.
Pause if the approval bundle changes
If the verified resolver or approval action API direction is rejected, pause or redesign this branch because durable approval updates depend on that full host seam.

Next step before merge
The remaining action is maintainer judgment on the public API/trust boundary plus CI inspection, not a narrow automated repair.

Security
Cleared: No concrete security bug was found in the diff; the admin-scoped injection helper and arbitrary metadata remain maintainer trust-boundary merge risks.

Review details

Best possible solution:

Land this only after maintainers accept the additive Gateway/plugin SDK contract as part of the approval API bundle, generated/client compatibility is acceptable, and the latest CI head is clean.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this is a feature/API PR. The PR body provides after-fix loopback Gateway proof for metadata persistence, live broadcast, history, and dedupe behavior.

Is this the best way to solve the issue?

Unclear pending maintainer contract approval. The implementation is narrow and covered, but the permanent Gateway/plugin SDK surface and admin trust boundary need explicit review with the companion PRs.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 0d0bddf03222.

Label changes

Label changes:

add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes terminal proof from a loopback Gateway plus external plugin CI showing after-fix metadata persistence, live event delivery, history round-trip, and idempotent retry behavior.

Label justifications:

P2: This is a normal-priority host API feature with limited blast radius but meaningful Gateway/plugin SDK review needs.
merge-risk: 🚨 compatibility: The PR adds public Gateway params, generated client fields, and a plugin SDK export that third-party clients may compile against.
merge-risk: 🚨 session-state: The PR changes persisted transcript message metadata, chat.history, live chat broadcast behavior, and idempotent append semantics.
merge-risk: 🚨 security-boundary: The PR exposes an admin-scoped helper for injecting metadata-bearing UI/status messages into sessions.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. A generic durable host seam for external HITL approval plugins is strategically useful because it keeps AgentKit/World ID out of core while enabling the workflow through supported APIs.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes terminal proof from a loopback Gateway plus external plugin CI showing after-fix metadata persistence, live event delivery, history round-trip, and idempotent retry behavior.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes terminal proof from a loopback Gateway plus external plugin CI showing after-fix metadata persistence, live event delivery, history round-trip, and idempotent retry behavior.

Evidence reviewed

PR surface:

Source +247, Tests +545, Docs 0, Other +16. Total +808 across 16 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	5	250	3	+247
Tests	6	546	1	+545
Docs	4	4	4	0
Config	0	0	0	0
Generated	0	0	0	0
Other	1	17	1	+16
Total	16	817	9	+808

What I checked:

Repository policy read: Read the root and scoped Gateway/protocol/plugin-SDK/docs AGENTS.md files; the relevant guidance treats Gateway protocol and plugin SDK additions as public compatibility-sensitive surfaces. (AGENTS.md:19, 91590132f68a)
Current main lacks the requested metadata fields: On current origin/main, ChatInjectParamsSchema only accepts sessionKey, message, and label, so the central PR behavior is not already implemented. (src/gateway/protocol/schema/logs-chat.ts:64, 0d0bddf03222)
Protocol and runtime surface expand in the PR: The diff adds optional idempotencyKey, command, interactive, and channelData to chat.inject, threads them through append/broadcast/history behavior, and returns successful dedupe responses. (src/gateway/server-methods/chat.ts:3703, 1a237ecf76ec)
Transcript append contract supports serialized idempotency: Current main already has an explicit idempotencyLookup: "scan" path under the transcript append queue/write lock; the PR uses that contract for chat.inject retries instead of ad hoc raw writes. (src/config/sessions/transcript-append.ts:237, 0d0bddf03222)
Plugin SDK helper is new: Current main has no src/gateway/operator-chat-client.ts and plugin-sdk/gateway-runtime does not export injectChatMessageOverGateway; the PR adds that helper as a new public SDK contract. (src/plugin-sdk/gateway-runtime.ts:35, 0d0bddf03222)
Related approval bundle is partly landed and partly open: The related approval action metadata PR at Expose plugin approval action metadata #82431 is merged, while the verified approval resolver at feat: add external plugin approval verification #82434 remains open, so this PR is part of an active API bundle rather than a standalone obsolete branch. (0c867eef756e)

Likely related people:

vincentkoc: Current-main blame and recent history point the existing chat.inject, transcript append, and Gateway SDK facade surfaces at Vincent Koc's recent Gateway/session work. (role: recent area contributor; confidence: medium; commits: b8fc2f658794, 0f7d9c957093, b35becfb1dfc; files: src/gateway/server-methods/chat.ts, src/gateway/server-methods/chat-transcript-inject.ts, src/config/sessions/transcript-append.ts)
steipete: Recent history shows Peter Steinberger touched Gateway protocol docs, Gateway auth/helper seams, and plugin SDK boundary refactors that frame this PR's API-shape decision. (role: adjacent protocol and SDK boundary contributor; confidence: medium; commits: 79e8edc7bdb8, 9ebe38b6e36b, bb01e49192d3; files: docs/gateway/protocol.md, src/plugin-sdk/gateway-runtime.ts, src/gateway/operator-approvals-client.ts)
Guardiola31337: The same contributor authored the already-merged approval action metadata PR and owns the external AgentKit integration that exercises this host API bundle. (role: adjacent feature author and external integration owner; confidence: medium; commits: 0c867eef756e, 1a237ecf76ec; files: src/gateway/protocol/schema/plugin-approvals.ts, src/plugin-sdk/approval-renderers.ts, src/gateway/operator-chat-client.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Guardiola31337 · 2026-05-17T20:56:45Z

@clawsweeper re-review

clawsweeper · 2026-05-17T20:58:24Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26003719822
Updated: 2026-05-17T21:58:57.923Z

Guardiola31337 · 2026-05-17T21:31:06Z

@clawsweeper re-review

I reran the exact API baseline acceptance check from the review finding on the current head c4a2b02d8337; it passes with no generated baseline diff:

$ pnpm plugin-sdk:api:check
OK docs/.generated/plugin-sdk-api-baseline.sha256

$ git diff -- docs/.generated/plugin-sdk-api-baseline.sha256
(no output)

clawsweeper · 2026-05-20T15:08:33Z

ClawSweeper PR egg

✨ Hatched: 🥚 common Clockwork Clawlet

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

Merged PRs are hatchable.
Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: 🥚 common.
Trait: watches the merge queue.
Image traits: location merge queue dock; accessory green check lantern; palette cobalt, lime, and pearl; mood watchful; pose peeking out from the egg shell; shell paper lantern shell; lighting warm desk-lamp glow; background tiny shells and proof notes.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Clockwork Clawlet in ClawSweeper.

What is this egg doing here?

Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

clawsweeper · 2026-05-20T15:08:42Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26171484447
Updated: 2026-05-20T15:19:01.178Z

Guardiola31337 · 2026-05-21T14:45:25Z

@clawsweeper hatch

clawsweeper · 2026-05-21T14:47:24Z

🦞👀
ClawSweeper PR egg hatch requested.

I queued a comment sync for this PR. If the egg is hatchable, ClawSweeper will generate the image once and update the existing review comment.
Action: PR egg hatch queued (workflow sweep.yml, event repository_dispatch).
The ASCII egg stays as the fallback.

Guardiola31337 · 2026-05-29T01:08:37Z

Closing this for now to keep the AgentKit HITL host slice minimal. The revised path no longer needs chat.inject metadata/status cards: external verification renders through plugin approval prompts and the verified resolver. We can reopen or file a narrower follow-up if maintainers want durable status cards later.

openclaw-barnacle Bot added docs Improvements or additions to documentation app: web-ui App: web-ui gateway Gateway runtime triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. size: S labels May 16, 2026

Guardiola31337 force-pushed the agentkit/chat-inject-reply-metadata branch 2 times, most recently from 6c7b19b to 8e1d366 Compare May 16, 2026 06:20

openclaw-barnacle Bot added proof: supplied External PR includes structured after-fix real behavior proof. and removed triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 16, 2026

Guardiola31337 force-pushed the agentkit/chat-inject-reply-metadata branch 4 times, most recently from 1deb731 to 40142a7 Compare May 16, 2026 06:54