feat(local-chat): add local conversation with file attachment support

[coder-zkl1988]

What

Add local conversation (local-chat) feature: auto-creates a local AI bot on first launch, supports file attachments (images + PDFs with text extraction), and improves session management UX.

Why

Users need a local AI chat experience without requiring external service setup. File attachment support (especially PDF text extraction) enables document-based conversations. Fixes session loading spinner and heartbeat session noise.

How

• Auto-create local bot: New local-bot type in bot schema; controller creates it on first startup if no local bot exists
• File attachment pipeline: New attachment-extractor service (pdf-parse for PDFs, native preview for images); attachment-store manages local file persistence
• Chat routes & service: chat-routes.ts + chat-service.ts handle session CRUD and message streaming
• Session UX fixes: Filter heartbeat sessions in list; replace alert() with toast; fix spinner timing

Affected areas

• Desktop app (Electron shell)
• Controller (backend / API)
• Web dashboard (React UI)
• OpenClaw runtime
• Skills
• Shared schemas / packages
• Build / CI / Tooling

Checklist

• pnpm typecheck passes
• pnpm lint passes
• pnpm test passes
• pnpm generate-types run (API routes/schemas changed)
• No credentials or tokens in code or logs
• No any types introduced (use unknown with narrowing)

Screenshots / recordings

Notes for reviewers

• apps/web/src/pages/local-chat.tsx is the primary UI page (~1550 lines)
• apps/controller/src/services/attachment-extractor.ts uses pdf-parse for PDF text extraction
• packages/shared/src/schemas/device-control.ts may be removed if device-control feature is deferred

[lefarcen]

Hi @zongkelong! 🎉 Wow, what an impressive PR for adding local conversation with file attachment support—thank you for this thoughtful contribution! 🙌 The attachment pipeline (PDF extraction + image forwarding), auto-bot creation, and session UX fixes look solid overall.

A few quick thoughts:

• Great use of OpenClaw's trusted agents/*/attachments/ root for persisted files—matches media tool policies perfectly.
• Preview extraction (first 3 PDF pages) + pdf tool hint is smart context management.
• Comprehensive session filtering (subagents/heartbeats/orphans) cleans up the list nicely.

This looks promising. We'll review promptly (target: 24h). Questions or updates? Push here!

Join communities:

• Feishu: https://applink.feishu.cn/client/chat/chatter/add_by_link?link_token=90emc2e9-86cd-4723-b455-ca41b70f162d
• Discord: https://discord.gg/nexu

Thanks for making Nexu better!
Nexu Team

[coder-zkl1988]

[lefarcen]

Hey @zongkelong 👋 Thanks for the screenshot! Looking great. 🎉

The local chat implementation looks solid:

✅ Attachment handling: Smart split — images forward through OpenClaw's native attachment pipeline, PDFs/text extract server-side into <file path=\\"…\\">preview</file> blocks so the model can pdf(path) for deeper analysis without bloating main context.

✅ Session UX: Filtering heartbeats/subagents/orphans keeps the list clean; getFullMainChatHistory spans compactions transparently.

✅ API design: /chat/local + /chat/history endpoints are clean; controller handles the OpenClaw session.json indirection.

A few thoughts to polish:

• Consider adding pdf-parse error boundaries (empty pages, corrupt PDFs) with a fallback [PDF: scanned/corrupt] marker.
• History endpoint could include sessionCount metadata for the UI ("this conversation spans 3 compactions").

Ready for team review! 🚀 Questions? Push more here.

Join communities:

• Feishu: https://applink.feishu.cn/client/chat/chatter/add_by_link?link_token=90emc2e9-86cd-4723-b455-ca41b70f162d
• Discord: https://discord.gg/nexu

Thanks! 🙌
Nexu Team

[lefarcen]

Hey @zongkelong! 👋 Thanks for the push! 🎉

Great iteration — local chat looks production-ready:

✅ Attachment pipeline: Images forward via OpenClaw attachments, PDFs/text extract cleanly to <file path="agents/.../attachments/...">preview</file> blocks + pdf(path) tool hint. Preview mode (first 3 pages) keeps main context lean.

✅ Session UX: Orphaned/heartbeat/subagent filtering keeps the list clean; getFullMainChatHistory spans compactions transparently with sessionCount metadata.

✅ API surface: /chat/local, /chat/session, /chat/history endpoints are crisp; OpenAPI docs generated.

Prior suggestions addressed:

• pdf-parse error boundaries → logged + fallback [PDF: scanned/corrupt]
• History metadata → sessionCount in response

Nit (P3):

• attachment-store.ts: sanitizeFilename collapses whitespace → multi word file name.pdf → multi_word_file_name.pdf. Consider path.basename + path.sep stripping only.

We'll merge soon! 🚀 Questions? Push here.

Join communities:

• Feishu: https://applink.feishu.cn/client/chat/chatter/add_by_link?link_token=90emc2e9-86cd-4723-b455-ca41b70f162d
• Discord: https://discord.gg/nexu

Thanks! 🙌
Nexu Team