# Task: Fix Robot agent configuration loading ## Identity - Task ID: 20260815-robot-config-loading-4f8c2d - Mode: Feature - Branch: codex/20260815-robot-config-loading-4f8c2d-robot-config-loading - Worktree: D:\Datas\OthersProjects\makelore-robot-config-loading-4f8c2d - Base commit: a4050f0a6567e8203630bf5d16b57f00c45caab8 - Owner: codex - Status: Ready for review ## Scope - Reproduce the Robot page state where a selected agent remains indefinitely in configuration loading and the edit action stays disabled after device binding. - Trace the Renderer typed API, page effects, and Main-owned Works Square route without weakening authentication, ETag, idempotency, or response validation. - Fix the smallest confirmed client-side cause and add a regression test at the user-visible page seam. ## Intent And Constraints - The edit button may be enabled only after a real, versioned agent configuration has loaded; do not bypass the loading/error state. - Preserve Main ownership of Works Square credentials and upstream headers, and retain strict numeric revision plus ETag equality checks. - Keep activation codes and upstream response details out of Renderer state, logs, task records, and test output. - Work only in the isolated linked worktree; do not alter or release the existing `main` integration owner. ## Project Context Loaded Task context: - Task ID: `20260815-robot-config-loading-4f8c2d` - Mode: `feature` - Branch: `codex/20260815-robot-config-loading-4f8c2d-robot-config-loading` - Worktree: `D:\Datas\OthersProjects\makelore-robot-config-loading-4f8c2d` - Base commit: `a4050f0a6567e8203630bf5d16b57f00c45caab8` - Other active local tasks: the existing `main` integration owner, completed Robot source task, and isolated release, AI Design, AI Programming, updater, and packaging tasks returned by the registry. - Overlap or semantic-conflict assessment: the completed Robot task establishes the relevant trust and state boundaries; no active peer owns the Robot page or typed hardware API. The same-base AI Design points task is confined to AI Design. Placeholder peer records have unrelated titles and isolated worktrees, so no semantic conflict blocks this diagnosis. Read: - `.project-docs/05-agent-entry/read-before-planning.md` - `.project-docs/05-agent-entry/memory-index.md` - `.project-docs/05-agent-entry/planning-gate.md` - this task record - `.project-docs/00-brief/project-positioning.md` - `.project-docs/00-brief/success-criteria.md` - `.project-docs/30-worklog/current-state.md` - `.project-docs/10-decisions/decision-index.md` - `.project-docs/20-architecture/system-overview.md` - `.project-docs/20-architecture/module-map.md` - `.project-docs/20-architecture/data-flow.md` - `.project-docs/40-domain/business-rules.md` - evidence, reflection, commitment, and stale-item indexes - every peer task record returned by `task_context.py status --json` Relevant understanding: - Project goal: provide a non-technical desktop workflow while keeping credentials and sensitive network behavior in Electron Main. - Current integrated focus: Robot is the single enabled hardware module and its typed Renderer → Host API → Main → Works Square chain is integrated. - Active task scope: restore the configuration-loading terminal state so the user can edit the selected agent after binding a device. - Active constraints: do not expose credentials/raw upstream errors, do not bypass revisions, and do not initialize Programming state on Robot routes. - Decisions affecting this task: one local account maps to one Xiaozhi binding; agents/devices are resources beneath it; Main owns auth/idempotency/ETags. - Evidence, reflections, or commitments affecting this task: the screenshot proves overview and device binding render successfully while the configuration pane remains loading; real production Robot smoke remains the decisive deployment check. - Files or modules likely involved: `src/pages/AiHardware/index.tsx`, `src/lib/ai-hardware.ts`, `electron/api/routes/ai-hardware.ts`, and their focused tests. - Unknowns, stale docs, or conflicts: the screenshot alone does not distinguish a never-settling promise from a rejected response followed by stale loading state; a red-capable page test is required before selecting a fix. Gate result: - Passed. ## Outcome - Reproduced the user-visible failure with a deterministic page test: after the configuration request rejected, the card still rendered `正在读取配置`, exposed no retry action, and kept editing disabled. - Split configuration loading from its terminal failure state. A failed read now renders a safe local error state with `重试读取配置`; a successful retry restores the prompt and enables editing only after a real configuration and revision have loaded. - Clear loading/error state when no agent is selected, preventing an abandoned request from leaving a stale spinner. - Extended the Main-owned upstream deadline through bounded response-body reading and JSON parsing. A response that returns headers and an initial chunk but never completes now terminates as the safe retryable `504 / AI_HARDWARE_TIMEOUT` envelope instead of leaving Renderer pending forever. - Preserved strict response schemas, ETag/revision equality, Main-owned authentication, idempotency, response-size limits, and upstream error redaction. - Cross-repository inspection found no current source-contract mismatch for agent configuration fields, revision numbers, or ETags. Production still needs to be checked for the current Xiaozhi image and Liquibase migrations if a retry reports a server error. ## Verification - Red page test on the pre-fix implementation: `pnpm exec vitest run tests/unit/ai-hardware-page.test.tsx -t "stops loading and lets the user retry after configuration loading fails"` — 1 failed, proving the stale loading state. - Red Main route test on the pre-fix implementation: stalled configuration response body exceeded the 100 ms test deadline without returning an envelope. - `corepack pnpm exec vitest run tests/unit/ai-hardware-page.test.tsx` — 25 passed. - `corepack pnpm exec vitest run tests/unit/ai-hardware-routes.test.ts` — 18 passed. - Focused Robot/Main regression suite across page, route, typed API, Host proxy, module navigation, layout gate, and provider gate — 7 files / 74 tests passed. - `corepack pnpm run typecheck` — passed. - ESLint on the four changed TypeScript/TSX files — passed. - `git diff --check` — passed; only Git line-ending conversion warnings were emitted. - Independent final Sol review — PASS; the reviewer reproduced the 7-file / 74-test result and found no code or documentation blocker. ## Follow-ups - After deployment, verify the Xiaozhi manager image includes numeric External API revision serialization and that Liquibase changesets `202608131500` and `202608131501` are applied if configuration reads still fail. - Perform a signed-in staging smoke: bind a device, load the selected agent configuration, edit `systemPrompt`, save with the returned revision, and confirm the updated prompt after refresh. ## Promotion Candidates - None recorded.