fix: surface safe terminal tool fallbacks by fuller-stack-dev · Pull Request #90872 · openclaw/openclaw

fuller-stack-dev · 2026-06-06T06:49:35Z

Summary

Add opt-in terminal fallback metadata through agent-core, session tool definitions, subscribe handling, and the embedded runner.
Surface safe terminal summaries for tool-loop and incomplete-turn exits, while keeping undeclared tool output neutral instead of leaking raw results.
Declare structured fallbacks for cron and web_fetch, and keep Docker image builds from carrying stale dist output.
Tighten delivery/side-effect evidence for channel replies, source-reply deliveries, context-engine pairing, compaction ownership, heartbeat lifecycle handling, and tool-plugin result preservation.

Contract note

terminalSummary and terminalResultFallback are intentionally public tool metadata for safe terminal presentation.
Tools opt in explicitly; undeclared raw tool output is not surfaced as a fallback.
Generic tool activity, accepted child-session spawns, messaging sends, cron additions, and replay-invalid aborts continue to suppress fallback model replay so side effects are not duplicated.
defineToolPlugin preserves intentional helper-created tool results while continuing to JSON-wrap bare text-shaped objects with content and details fields.

Verification

node scripts/run-vitest.mjs src/plugin-sdk/tool-plugin.test.ts src/agents/embedded-agent-runner/run.incomplete-turn.test.ts src/agents/embedded-agent-subscribe.handlers.tools.test.ts src/auto-reply/reply/agent-runner.runreplyagent.e2e.test.ts -- --reporter=dot
pnpm check:docs
pnpm lint --threads=8
pnpm plugin-sdk:api:check
.agents/skills/autoreview/scripts/autoreview --mode branch --base upstream/main --codex-bin /Users/jason/.codex/openclaw-pr-autopilot/bin/codex-persist-sessions --model codex=gpt-5.5 --thinking codex=high
git diff --check

Real behavior proof

Behavior addressed: Channel-facing agents that ended a turn after successful tool work could reply with planning text, repeat promises, or expose unsafe raw fallback text instead of delivering the completed tool result.

Real environment tested: A live Discord-backed OpenClaw stack using the patched image and a connected bot. Identifying stack, bot, channel, image, and run IDs are intentionally omitted from this public PR.

Exact steps or command run after this patch: Sent live prompts that exercised a scheduler/cron path and a web_fetch tool-loop timeout path through the running gateway.

Evidence after fix:

Redacted live channel output, scheduler path:

The requested scheduler state cannot be checked from this runtime because no scheduler, cron, gateway, or exec tool is available in this channel session. I cannot claim a live cron check without that tool.

Redacted live channel output, web_fetch terminal fallback path:

URL: https://example.com
Final URL: https://example.com
Status: 200
Title: Example Domain
Cached: true
Truncated: false

Observed result after fix: The channel received user-visible results for both proof cases. The web_fetch fallback included URL, final URL, status, title, cache state, and truncation state, with no raw unsafe tool dump. The scheduler path returned a direct capability blocker instead of a promise to perform an unavailable check.

What was not tested: Broad cross-channel E2E beyond Discord was not rerun. One unrelated live runtime metadata drift was observed during proof and is omitted here because it is not part of this patch.

clawsweeper · 2026-06-06T06:52:24Z

Thanks for the contribution. I reviewed the branch, and this PR is not a good landing base for OpenClaw.

Close: the terminal-fallback problem is useful, but this branch is no longer a viable landing base after an explicit maintainer rejection and code inspection showing broad public SDK, core tool-contract, and embedded-runner rewrites.

So I’m closing this PR rather than keeping an unmergeable branch open. A new narrow PR that carries only the useful part is welcome.

Review details

Best possible solution:

Close this branch as the landing candidate and pursue a narrow replacement PR that fixes one terminal-fallback delivery path, with any public Plugin SDK API handled as a separate maintainer-approved contract change.

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

No high-confidence reviewer-run reproduction was established in this read-only pass. The PR's redacted live Discord proof and source inspection make the reported terminal fallback failure plausible, but current-head behavior was not independently reproduced.

Is this the best way to solve the issue?

No. This branch is a plausible exploration, but the best maintainable solution is a much narrower runtime repair plus a separate product/API decision for durable Plugin SDK fallback metadata.

Security review:

Security review cleared: No concrete security or supply-chain regression was found; the diff does not add dependencies or workflows, but any replacement must keep terminal fallback output explicitly public and redacted.

AGENTS.md: found and applied where relevant.

What I checked:

Repository policy read: Root AGENTS.md and scoped guides for agents, embedded-runner/run, tools, Plugin SDK, docs, scripts, and extensions were read; Plugin SDK and fallback compatibility rules affected the review. (AGENTS.md:18, f1b8827d20c8)
Live PR scale and state: Live PR inspection showed current head e7ad604, 75 changed files, +15999/-1907, mergeable but unstable, and no protected maintainer/security/release-blocker labels. (e7ad60421281)
Maintainer decision: steipete commented on 2026-06-14 that this PR is not landing and that the 15k LOC approach cannot be right.
Public Plugin SDK expansion: The PR head adds terminalResultFallback to tool plugin definitions and exports toolResult(...), turning the fix into a new public Plugin SDK contract. (src/plugin-sdk/tool-plugin.ts:50, e7ad60421281)
Core tool contract expansion: The PR head adds AgentToolTerminalSummary, AgentToolTerminalResultFallback, terminalSummary, and terminalResultFallback to core agent tool types. (packages/agent-core/src/types.ts:439, e7ad60421281)
Broad runtime rewrite: The PR head adds a new embedded-runner tool-loop fallback module and wires fallback resolution into run.ts, confirming this is a broad runner rewrite rather than a narrow repair. (src/agents/embedded-agent-runner/run/tool-loop-fallback.ts:1, e7ad60421281)

Likely related people:

steipete: Merged adjacent current-main agent/reply fixes and left the explicit June 14 decision that this branch shape should not land. (role: recent merger and branch decision commenter; confidence: high; commits: 81924cfd5e61, ecaebfc51b4a, c67dc59b02b0; files: src/agents/embedded-agent-runner/run.ts, src/agents/embedded-agent-runner/run/incomplete-turn.ts, src/auto-reply/reply/agent-runner.ts)
ai-hpc: Authored the merged thinking-only errored-turn retry work that recently touched the embedded runner and incomplete-turn paths this PR rewrites. (role: recent adjacent agent-runner contributor; confidence: medium; commits: ecaebfc51b4a; files: src/agents/embedded-agent-runner/run.ts, src/agents/embedded-agent-runner/run/incomplete-turn.ts)
sandieman2: Authored the merged final-reply and routed-thread delivery work adjacent to this PR's source-reply and channel-delivery changes. (role: recent adjacent reply-delivery contributor; confidence: medium; commits: c67dc59b02b0; files: src/auto-reply/reply/agent-runner.ts, src/agents/embedded-agent-subscribe.handlers.tools.ts)
joelnishanth: Authored the merged length-limited response handling that touched incomplete-turn and terminal trajectory behavior adjacent to this PR. (role: recent adjacent terminal-run contributor; confidence: medium; commits: 81924cfd5e61; files: src/agents/embedded-agent-runner/run/incomplete-turn.ts, src/agents/embedded-agent-runner/run/attempt-trajectory-status.ts, src/agents/embedded-agent-subscribe.ts)
ragesaq: Current-main blame and log show recent direct work on the incomplete-turn and message-tool final-reply paths that form the base this PR rewrites. (role: recent adjacent fallback/delivery contributor; confidence: medium; commits: a15427d605fe; files: src/agents/embedded-agent-runner/run/incomplete-turn.ts, src/auto-reply/reply/agent-runner.ts, src/plugin-sdk/tool-plugin.ts)

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

fuller-stack-dev · 2026-06-06T07:10:21Z

Visual verification request: verify a Discord-backed run surfaces safe scheduler/web_fetch terminal fallback without raw tool output.

fuller-stack-dev · 2026-06-06T07:40:37Z

@clawsweeper re-review

clawsweeper · 2026-06-06T07:40:40Z

🦞🧹
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/27056489515
Updated: 2026-06-06T07:50:01.380Z

# Conflicts: # docs/.generated/plugin-sdk-api-baseline.sha256

# Conflicts: # src/agents/embedded-agent-runner/run/attempt.ts # src/agents/embedded-agent-runner/run/incomplete-turn.ts

steipete · 2026-06-14T19:00:49Z

We are not landing this. This is 15k LOC and can't possibly be the right approach.

fuller-stack-dev · 2026-06-14T23:25:39Z

Closing as superseded by #93073.

This PR established the real Discord-facing failure and contains useful investigation/proof history, but the 75-file, +15,999/-1,907 approach adds broad public tool/fallback contracts and is not the implementation we want to land. #93073 carries the motivating evidence forward and replaces this with a narrow typed post-tool empty-final recovery using the existing bounded continuation, with fail-closed replay handling for unclassified tools and no natural-language regex parsing or raw-result fallback.

Please continue implementation review and proof discussion on #93073. Reopen this PR only if concrete evidence shows a distinct required behavior that the narrow replacement cannot cover and that requires the broader public fallback contract.

steipete · 2026-06-15T08:40:00Z

Superseded by #93228.

The replacement keeps this PR's goal, but removes the natural-language classifier and large English-specific regular expressions. It uses explicit harness/protocol terminal states, structured replay-safety evidence, and post-middleware tool summaries instead. The original contribution remains credited through Co-authored-by: Jason (Json) <[email protected]>.

Thank you @fuller-stack-dev for identifying and implementing the original safe-terminal-fallback direction.

fuller-stack-dev mentioned this pull request Jun 6, 2026

fix: surface safe terminal tool fallbacks #90871

Closed

openclaw-barnacle Bot added channel: discord Channel integration: discord docker Docker and sandbox tooling agents Agent runtime and tooling size: XL triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels Jun 6, 2026

fuller-stack-dev force-pushed the codex/safe-terminal-tool-fallbacks branch from f360f5f to 768d38d Compare June 6, 2026 06:50

fuller-stack-dev force-pushed the codex/safe-terminal-tool-fallbacks branch from 768d38d to fdd98e0 Compare June 6, 2026 07:40

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 Jun 6, 2026

fuller-stack-dev force-pushed the codex/safe-terminal-tool-fallbacks branch from fdd98e0 to d541d51 Compare June 6, 2026 08:13

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 6, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 6, 2026

fuller-stack-dev force-pushed the codex/safe-terminal-tool-fallbacks branch from d541d51 to 72faa63 Compare June 6, 2026 08:23

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 6, 2026

fuller-stack-dev force-pushed the codex/safe-terminal-tool-fallbacks branch from 72faa63 to 8f274c9 Compare June 6, 2026 08:29

fuller-stack-dev added 21 commits June 14, 2026 03:40

fix: preserve delivery and request evidence

a41cdfc

fix: preserve prompt and proxy boundaries

f3b18ce

fix: preserve terminal action evidence

6eec191

fix: preserve final reply evidence

fb75f9a

fix: bound terminal fallback delivery

5fcc1cd

fix: preserve visible delivery evidence

57101a6

fix: require current terminal evidence

86980ec

fix: preserve terminal refusal outcomes

1c1be4e

fix: recognize quoted action context

acae874

fix: distinguish progress from terminal replies

66c757d

Merge remote-tracking branch 'upstream/main' into autopilot/pr-90872

ef0119e

# Conflicts: # docs/.generated/plugin-sdk-api-baseline.sha256

Merge remote-tracking branch 'upstream/main' into autopilot/pr-90872

c678fd2

# Conflicts: # docs/.generated/plugin-sdk-api-baseline.sha256

fix: preserve trusted delivery outcomes

ee27d50

Merge remote-tracking branch 'upstream/main' into autopilot/pr-90872

9d66e10

fix: harden fallback evidence classification

e91c6d5

Merge upstream/main into codex/safe-terminal-tool-fallbacks

fa7b965

fix: preserve normalized message delivery outcomes

ddfff9a

fix: tighten terminal fallback safety

6bbab7d

fix: preserve terminal failure evidence

3f01a86

fix: unify terminal failure classification

bcf2d30

Merge remote-tracking branch 'upstream/main' into autopilot/pr-90872

bbbcdf2

# Conflicts: # src/agents/embedded-agent-runner/run/attempt.ts # src/agents/embedded-agent-runner/run/incomplete-turn.ts

fuller-stack-dev added 3 commits June 14, 2026 13:02

fix: tighten fallback delivery evidence

e18bd5d

fix: retain partial delivery evidence

2a48ab8

fix: preserve terminal failure signals

e7ad604

hannesrudolph mentioned this pull request Jun 14, 2026

fix: continue after empty post-tool replies #93062

Closed

fuller-stack-dev mentioned this pull request Jun 14, 2026

fix(agents): retry empty post-tool final turns #93073

Merged

steipete mentioned this pull request Jun 15, 2026

fix(agents): replace prose terminal classifiers #93228

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix: surface safe terminal tool fallbacks#90872

fix: surface safe terminal tool fallbacks#90872
fuller-stack-dev wants to merge 111 commits into
openclaw:mainfrom
fuller-stack-dev:codex/safe-terminal-tool-fallbacks

fuller-stack-dev commented Jun 6, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 6, 2026 •

edited

Loading

Uh oh!

fuller-stack-dev commented Jun 6, 2026 •

edited

Loading

Uh oh!

fuller-stack-dev commented Jun 6, 2026

Uh oh!

clawsweeper Bot commented Jun 6, 2026 •

edited

Loading

Uh oh!

steipete commented Jun 14, 2026

Uh oh!

fuller-stack-dev commented Jun 14, 2026

Uh oh!

steipete commented Jun 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

fuller-stack-dev commented Jun 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Contract note

Verification

Real behavior proof

Uh oh!

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

Uh oh!

Uh oh!

fuller-stack-dev commented Jun 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fuller-stack-dev commented Jun 6, 2026

Uh oh!

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

Uh oh!

Uh oh!

steipete commented Jun 14, 2026

Uh oh!

fuller-stack-dev commented Jun 14, 2026

Uh oh!

steipete commented Jun 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fuller-stack-dev commented Jun 6, 2026 •

edited

Loading

clawsweeper Bot commented Jun 6, 2026 •

edited

Loading

fuller-stack-dev commented Jun 6, 2026 •

edited

Loading

clawsweeper Bot commented Jun 6, 2026 •

edited

Loading