refactor(plugin-sdk): consolidate tool result helpers by RomneyDa · Pull Request #99740 · openclaw/openclaw

RomneyDa · 2026-07-04T01:27:00Z

What Problem This Solves

Portable agent tool-result construction was duplicated across multiple plugins. Exact pretty-JSON result builders repeatedly recreated the same contract: one text block containing JSON.stringify(payload, null, 2) plus the same typed payload in details.

Why This Change Was Made

This adds a narrow openclaw/plugin-sdk/tool-results entrypoint that exposes the canonical typed textResult and jsonResult helpers, then migrates only callers with identical contracts. MCP structured/error results, browser sanitization, media/file results, approvals, channel presentation, transport envelopes, and caller-specific failure semantics remain with their existing owners.

The consolidation removes local constructors and one duplicate result type while preserving the existing model-facing text and structured details behavior.

User Impact

No intended behavior change. Plugin tools keep returning the same text and details payloads. Plugin authors gain a small supported SDK seam for portable text and pretty-JSON agent results.

SDK surface metric and merge risk

Public entrypoints: +1 (323 -> 324)
Public exports: +3 (10,425 -> 10,428)
Public callable exports: +2 (5,237 -> 5,239)

This is an additive public SDK contract, so the matching package export, API metadata/checksum, docs, and exact surface-budget ceilings are updated together. The merge risk is limited to that additive surface; no existing SDK entrypoint is removed or changed, and migrated runtime shapes are unchanged.

Evidence

node scripts/plugin-sdk-surface-report.mjs --check
- Public SDK totals: 324 entrypoints, 10,428 exports, 5,239 callable exports.
pnpm plugin-sdk:api:check
pnpm plugin-sdk:check-exports
Focused Vitest proof passed across nine routed shards: 281 tests covering the SDK surface/contracts and migrated Feishu, Google Meet, Lobster, QQBot, Voice Call, and Zalouser callers.
Testbox-through-Crabbox changed gate and full build passed: provider blacksmith-testbox, id tbx_01kwq95wx5ftcsx4xprr9kc5ja, Actions run 28716970734.
Fresh Codex autoreview: clean, no accepted/actionable findings, confidence 0.93.

clawsweeper · 2026-07-04T01:28:19Z

Codex review: needs maintainer review before merge. Reviewed July 4, 2026, 7:48 PM ET / 23:48 UTC.

Summary
Adds openclaw/plugin-sdk/tool-results with textResult and jsonResult, migrates matching bundled plugin JSON result helpers, and updates SDK docs/package/export metadata.

PR surface: Source -76, Tests +19, Docs +2, Config +4, Generated 0, Other +4. Total -47 across 24 files.

Reproducibility: not applicable. this is an additive SDK/refactor PR rather than a bug report. Source inspection compared current-main helper behavior, the PR helper/facade, and migrated call sites.

Review metrics: 1 noteworthy metric.

Public SDK surface: +1 entrypoint, +3 exports, +2 callable exports. The additive public API surface is the maintainer decision because external plugins may depend on it after release.

Stored data model
Persistent data-model change detected: serialized state: extensions/feishu/src/bitable.ts, serialized state: extensions/feishu/src/chat.ts, serialized state: extensions/feishu/src/docx.ts, serialized state: extensions/feishu/src/tool-result.test.ts, serialized state: extensions/feishu/src/tool-result.ts, serialized state: extensions/google-meet/index.ts, and 8 more. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🌊 off-meta tidepool
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

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

Risk before merge

[P1] Accepting this PR makes openclaw/plugin-sdk/tool-results a supported public SDK subpath after release, so future removal or behavior changes need compatibility handling.

Maintainer options:

Accept the SDK seam (recommended)
Merge if maintainers are comfortable supporting openclaw/plugin-sdk/tool-results as a stable narrow helper while existing SDK imports remain intact.
Keep the helper internal
Remove the package export and public docs if maintainers want this consolidation only for bundled/internal callers.
Pause for SDK direction
Pause or close this PR if maintainers want a broader tool-result API design before adding another supported SDK subpath.

Next step before merge

[P2] Manual review is needed because the remaining action is deciding whether to support a new public plugin SDK import path.

Security
Cleared: No concrete security or supply-chain concern was found; the diff adds an SDK helper/export and migrates callers without dependency, workflow, lockfile, download, permission, or secret-handling changes.

Review details

Best possible solution:

Land after maintainers explicitly accept the narrow public SDK seam and keep the package export, entrypoint metadata, API budget/baseline, docs, and focused contract tests aligned.

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

Not applicable; this is an additive SDK/refactor PR rather than a bug report. Source inspection compared current-main helper behavior, the PR helper/facade, and migrated call sites.

Is this the best way to solve the issue?

Yes, if maintainers accept the API; the narrow subpath is cleaner than exposing more of the broad agent helper surface. If maintainers do not want a public contract, the safer alternative is keeping the helper internal.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 7608d38597c0.

Label changes

Label justifications:

P2: This is a bounded SDK/API improvement with limited immediate user-facing urgency but maintainer-visible compatibility impact.
merge-risk: 🚨 compatibility: The PR adds a new public plugin SDK subpath that external plugins may import after release.
rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external contributor proof gate does not apply because the PR author association is MEMBER; the PR body still includes focused command, CI, and Testbox evidence.

Evidence reviewed

PR surface:

Source -76, Tests +19, Docs +2, Config +4, Generated 0, Other +4. Total -47 across 24 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	16	57	133	-76
Tests	2	33	14	+19
Docs	1	2	0	+2
Config	1	4	0	+4
Generated	1	2	2	0
Other	3	7	3	+4
Total	24	105	152	-47

What I checked:

Repository policy applied: The plugin SDK scoped guide treats public subpaths as intentional supported contracts and requires docs, entrypoint metadata, package exports, API baseline, and checks to stay aligned. (src/plugin-sdk/AGENTS.md:81, 7608d38597c0)
Current main helper contract: Current main already has agent tool helpers returning one text block plus details, including pretty JSON for jsonResult. (src/agents/tools/common.ts:394, 7608d38597c0)
PR helper preserves runtime shape: The PR moves textResult and generic jsonResult into a narrow helper with the same text-plus-details result shape. (src/agents/tools/tool-results.ts:3, 6a38d592cbd9)
Public SDK facade is narrow: The new SDK facade exports only the result type and the two helper functions rather than the broad agent tool helper module. (src/plugin-sdk/tool-results.ts:1, 6a38d592cbd9)
Package export added: The diff adds ./plugin-sdk/tool-results to package exports, making the helper a supported import path after release. (package.json:1436, 6a38d592cbd9)
SDK metadata aligned: The new subpath is listed in plugin SDK entrypoint metadata and docs metadata, matching the public-surface checklist. (scripts/lib/plugin-sdk-entrypoints.json:332, 6a38d592cbd9)

Likely related people:

steipete: History search found Peter Steinberger commits extracting agent tool result helpers and recently adjusting plugin SDK surface budgets. (role: introduced current helper behavior and adjacent SDK budget contributor; confidence: medium; commits: 8e568142f61b, 13c2f22240e4, 6aeb0575cfd1; files: src/agents/tools/common.ts, scripts/plugin-sdk-surface-report.mjs)
vincentkoc: History search found a comparable public plugin SDK subpath addition with package export, entrypoint metadata, source, and tests. (role: plugin SDK surface contributor; confidence: medium; commits: 66701d5a1e16; files: package.json, scripts/lib/plugin-sdk-entrypoints.json, src/plugin-sdk/opencode.ts)
RomneyDa: Beyond this PR, Dallin Romney recently touched SDK runtime/export tooling and the SDK surface report on current main. (role: recent adjacent SDK tooling contributor; confidence: medium; commits: 6c53dfa1df99; files: src/plugin-sdk/infra-runtime.ts, scripts/plugin-sdk-surface-report.mjs)

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.

Review history (7 earlier review cycles)

reviewed 2026-07-04T02:56:01.709Z sha 2b3b82a :: needs maintainer review before merge. :: none
reviewed 2026-07-04T18:15:03.499Z sha 4cf5883 :: needs maintainer review before merge. :: none
reviewed 2026-07-04T18:20:57.124Z sha 4cf5883 :: needs maintainer review before merge. :: none
reviewed 2026-07-04T19:13:19.005Z sha 7d1c455 :: needs maintainer review before merge. :: none
reviewed 2026-07-04T19:47:23.026Z sha 9dcb2cc :: needs maintainer review before merge. :: none
reviewed 2026-07-04T19:55:32.627Z sha 9dcb2cc :: needs maintainer review before merge. :: none
reviewed 2026-07-04T20:22:58.470Z sha 7689046 :: needs maintainer review before merge. :: none

RomneyDa · 2026-07-04T02:01:03Z

@clawsweeper re-review

clawsweeper · 2026-07-04T02:01:06Z

🦞🧹
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.

github-actions · 2026-07-04T19:06:59Z

Dependency graph guard cleared

This PR no longer has blocked dependency graph changes. A future dependency graph change requires a fresh /allow-dependencies-change comment after the guard blocks that new head SHA.

Current SHA: 6a38d592cbd905cd312c9841c023ddaaaf1f39ee

RomneyDa · 2026-07-04T19:15:02Z

@clawsweeper re-review

clawsweeper · 2026-07-04T19:15:04Z

🦞🧹
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.

RomneyDa · 2026-07-04T19:43:09Z

@clawsweeper re-review

clawsweeper · 2026-07-04T19:43:12Z

🦞🧹
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.

* refactor(plugin-sdk): consolidate tool result helpers * docs(plugin-sdk): tighten tool result guidance * refactor(feishu): use tool results directly

RomneyDa force-pushed the refactor/tool-results-consolidation branch from 53906ca to ec9de11 Compare July 4, 2026 01:38

RomneyDa force-pushed the refactor/tool-results-consolidation branch from ec9de11 to c626a35 Compare July 4, 2026 01:49

RomneyDa force-pushed the refactor/tool-results-consolidation branch from c626a35 to 81ae6fb Compare July 4, 2026 02:00

clawsweeper Bot added the status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. label Jul 4, 2026

RomneyDa force-pushed the refactor/tool-results-consolidation branch 2 times, most recently from 4cf5883 to 7d1c455 Compare July 4, 2026 19:06

github-actions Bot added the dependencies-changed PR changes dependency-related files label Jul 4, 2026

clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. and removed rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. labels Jul 4, 2026

RomneyDa force-pushed the refactor/tool-results-consolidation branch from 7d1c455 to 9dcb2cc Compare July 4, 2026 19:27

github-actions Bot removed the dependencies-changed PR changes dependency-related files label Jul 4, 2026

openclaw-barnacle Bot added size: M and removed size: S labels Jul 4, 2026

RomneyDa added 3 commits July 4, 2026 16:34

refactor(plugin-sdk): consolidate tool result helpers

539f67a

docs(plugin-sdk): tighten tool result guidance

6ab1537

refactor(feishu): use tool results directly

6a38d59

RomneyDa force-pushed the refactor/tool-results-consolidation branch from 7689046 to 6a38d59 Compare July 4, 2026 23:42

RomneyDa merged commit bfffa95 into main Jul 4, 2026
98 checks passed

RomneyDa deleted the refactor/tool-results-consolidation branch July 4, 2026 23:50

github-actions Bot mentioned this pull request Jul 5, 2026

📡 Upstream Digest — 2026-07-05 02:14 UTC curtismercier/openclaw-mods#1210

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

refactor(plugin-sdk): consolidate tool result helpers#99740

refactor(plugin-sdk): consolidate tool result helpers#99740
RomneyDa merged 3 commits into
mainfrom
refactor/tool-results-consolidation

RomneyDa commented Jul 4, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

RomneyDa commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

RomneyDa commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

RomneyDa commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

RomneyDa commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

SDK surface metric and merge risk

Evidence

Uh oh!

clawsweeper Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RomneyDa commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency graph guard cleared

Uh oh!

RomneyDa commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RomneyDa commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

RomneyDa commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

github-actions Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading