feat(openclaw): add typed synopsis stubs for externalized tool results

[huangxun375-stack]

Description

Add typed Tool Stub support for externalized tool results. This keeps OpenViking's existing externalization and ref-based recall flow, while replacing simple head/tail previews with deterministic, type-aware summaries.

This design is inspired by LCM/lossless-claw's tool stubbing approach, adapted to OpenViking's OpenClaw integration and session storage model with deterministic typed synopsis generation and ref-based drilldown rather than LLM summarization.

Related Issue

N/A

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test update

Changes Made

• Added deterministic typed synopsis generation for externalized tool results, covering json, csv, tsv, yaml, xml, code, text, and unknown.
• Updated tool result stubs to include structured synopsis metadata, original-content refs, hash, size info, and read/search/list exploration hints.
• Preserved existing externalization thresholds and ref-based recall behavior.
• Added regression coverage for synopsis generation, externalization behavior, threshold boundaries, aggregate budget handling, raw payload recall, and API metadata exposure.
• Added docs/design/tool-stub-design.md documenting the Tool Stub behavior and current boundaries.

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have tested this on the following platforms:
  • Linux
  • macOS
  • Windows

Test command run in a clean worktree:

python -m pytest tests/session/test_tool_result_synopsis.py tests/session/test_tool_result_externalization.py tests/server/test_api_sessions.py::test_tool_result_externalization_read_and_search -q --no-cov

Result: 29 passed, 4 warnings

The warnings are existing Pydantic deprecation warnings from the current dependency stack.

Checklist

• My code follows the project's coding style
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• Any dependent changes have been merged and published

Screenshots (if applicable)

N/A

Additional Notes

This PR intentionally does not add LLM summarization. The current implementation is deterministic and rule-based only.

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🏅 Score: 90

🧪 PR contains tests

🔒 No security concerns identified

✅ No TODO sections

🔀 No multiple PR themes

⚡ No major issues detected

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.

[ZaynJarvis]

cc @100yenadmin

[huangxun375-stack]

Hi @100yenadmin, I really like lossless-claw’s approach to keeping large tool outputs recoverable while avoiding dumping the full payload back into the active context. The file_xxx stub + drilldown path is a clean design.

This PR is inspired by that pattern. OpenViking already had a basic large tool-output externalization / preview path, and this PR builds on it by adding a typed / deterministic synopsis for session tool results: large outputs stay recoverable, while the active context gets a compact typed stub plus read/search/list drilldown.

If you have time, I’d really appreciate a quick design sanity check, especially on whether the typed synopsis choices feel reasonable and aligned with a recoverable stub + drilldown model.

Thanks again for the inspiration.