💻 Change Type

• ✨ feat
• ♻️ refactor

🔀 Description of Change

Page-agent tools (initPage / editTitle / getPageContent / modifyNodes / replaceText) used to run inside the renderer's mounted Lexical instance via EditorRuntime. This PR moves the execution path to the server, against a @lobehub/editor/headless instance, with the renderer reduced to a sync target.

Why

• The renderer-bound path made every tool call dependent on the live editor (editor unmounted → tool failed; user navigated away → silent state drift; tab switch / network blip → broken stream).
• All other server-executed tools already feed naturally into our OTel gen-ai + agent-signal + documentHistories audit trail. Page-agent was the only blind spot.
• Silent failures (LLM reports success but Lexical didn't actually change) had no observability — the new path detects them at the export boundary.

How it works now

LLM → BuiltinToolsExecutor (server) sees manifest.executors=['server']
   ↓
PageAgentExecutionRuntime (shell) → PageAgentRuntimeService (impl at registration site)
   ├─ DocumentModel.findById(docId)
   ├─ createHeadlessEditor() + hydrate from editorData/content
   ├─ EditorRuntime.setEditor(headless.kernel) + setTitleHandlers
   ├─ run the 5 page-agent APIs (shared client/server implementation)
   ├─ headless.export() → silent-failure invariant check
   └─ DocumentService.updateDocument(docId, …, saveSource: 'llm_call')
       └─ writes documents row + appends documentHistories (free audit trail)
   ↓ tool_end event delivers result.state.document{Content,EditorData,Title,Id}
PageAgentExecutor.onAfterCall (renderer)
   ├─ EditorRuntime.applyServerSnapshot → editor.setDocument('json', editorData, { keepId: true })
   └─ useDocumentStore.applyServerSnapshot → clear dirty + advance lastSaved*

Layout (follows agent-documents / self-iteration convention)

• packages/builtin-tool-page-agent/src/ExecutionRuntime/index.ts — runtime shell + PageAgentRuntimeService contract; package stays free of @lobehub/editor / @lobechat/editor-runtime static imports
• packages/builtin-tool-page-agent/src/client/executor/index.ts — git mv from src/executor/index.ts; gains onAfterCall to sync renderer state
• src/server/services/toolExecution/serverRuntimes/pageAgent.ts — registration site; directly imports EditorRuntime + createHeadlessEditor, implements the 5 service callbacks, computes editorData hash before/after for silent-failure detection
• packages/editor-runtime/src/EditorRuntime.ts — new applyServerSnapshot() that pushes a server-produced snapshot into the live editor without triggering the auto-save loop
• src/store/document/slices/editor/action.ts — matching store action that marks the row clean after a server write
• src/features/PageEditor/StoreUpdater.tsx — removes the now-dead LLM afterMutateHandler wiring (human-edit path untouched)

Package exports dropped ./executor (the slot used to be a renderer-only executor), gained ./executionRuntime. Existing consumer (src/store/tool/slices/builtin/executors/lobe-page-agent.ts) updated to import from ./client.

🧪 How to Test

• Tested locally
• Added/updated tests

Automated:

• packages/builtin-tool-page-agent: 24/25 tests pass (1 pre-existing baseline failure unrelated to this PR; see commit history on client/executor/index.test.ts).
• src/server/services/toolExecution/** + src/store/document/slices/editor/**: 230/230 pass.
• Project-wide `bun run type-check` is clean for all changed files (pre-existing drizzle-orm dual-copy noise unaffected).

Manual:

1. Open a page editor in a topic (scope=page).
2. Ask the LLM to edit the document (e.g. `add a paragraph about X`, `change the title to Y`, `replace 'foo' with 'bar'`).
3. Confirm:
   • The DB `documents.editorData` / `content` updates, and a `documentHistories` row gets appended with `saveSource='llm_call'`.
   • The live editor reflects the change without a refresh and the dirty indicator stays clean.
   • Closing & reopening the page yields the same content (no client-only state).

📝 Additional Information

Invariant violation is surfaced as a console.warn plus a state.invariantViolation = { apiName, kind, detail } field on the tool result. `kind` is one of:

• silent-no-op — handler reported a successful mutation but the editorData hash did not change (e.g. `modifyNodes` operations all pointed at non-existent node IDs).
• unexpected-mutation — editor state changed even though the handler reported no successful change.

Stability boundary: `editorChanged` is computed by hashing the exported `editorData` before and after the handler runs; `editTitle` is exempt because the title lives outside `editorData`.

Not in this PR: surfacing invariant violations in the UI, agent-signal source events on violation, and richer trace headers (these belong to the broader tracing-foundation work this PR unblocks).

🤖 Generated with Claude Code