# Task: Fix Robot configuration response validation ## Identity - Task ID: 20260815-robot-config-schema-8e2c41 - Mode: Feature - Branch: codex/20260815-robot-config-schema-8e2c41-robot-config-schema - Worktree: D:\Datas\OthersProjects\makelore-robot-config-schema-8e2c41 - Base commit: a26a53a7f4b1326be3084955029a65ef1f79929a - Owner: codex - Status: Ready for Integration ## Scope - Reproduce the production Robot configuration read failure with the exact safe response shape and field lengths reported by Works Square logs. - Identify the precise Main or Renderer validation rule that rejects a successful versioned configuration response. - Align the client contract with the already deployed Xiaozhi/Works Square public schema without weakening exact-key validation, bounds, ETag/revision equality, authentication, or error redaction. - Add regression coverage at the rejecting seam and the user-visible typed API/page path. ## Intent And Constraints - Treat the upstream `200 application/json`, numeric revision, and Works `200` as confirmed evidence that the failure is downstream client validation, not device binding or authentication. The canonical strong ETag is confirmed only on the Xiaozhi-to-Works hop; the deployed compressed Works response was independently observed as canonical weak `W/"0"`. - Use only safe field names, types, and lengths from the supplied logs; do not capture tokens, raw prompts, agent/device identifiers, or raw response bodies in tests or task records. - Preserve strict DTO projection and bounded field validation. Change only rules proven inconsistent with the server contract. - Keep Renderer free of credentials/raw upstream responses and preserve Main ownership of Works Square access and ETag handling. - 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-schema-8e2c41` - Mode: `feature` - Branch: `codex/20260815-robot-config-schema-8e2c41-robot-config-schema` - Worktree: `D:\Datas\OthersProjects\makelore-robot-config-schema-8e2c41` - Base commit: `a26a53a7f4b1326be3084955029a65ef1f79929a` - Other active local tasks: the existing `main` integration owner plus isolated release, packaging, AI Design, AI Programming, and completed Robot tasks returned by the registry. - Overlap or semantic-conflict assessment: the immediately preceding Robot loading task is completed and integrated, and establishes the relevant error/retry and timeout behavior. No active peer owns the Robot response-schema validators. Packaging tasks are read/build-only snapshots; AI Design and AI Programming scopes do not overlap this contract fix. Read: - `.project-docs/05-agent-entry/read-before-planning.md` - `.project-docs/05-agent-entry/planning-gate.md` - `.project-docs/05-agent-entry/memory-index.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 registered peer task record's Scope, Intent And Constraints, and Promotion Candidates sections Relevant understanding: - Project goal: keep a non-technical desktop workflow while Electron Main owns credentials, upstream network access, revisions, and safe response projection. - Current integrated focus: Robot is the single hardware module; the previous fix now exposes a terminal configuration error instead of an endless spinner. - Active task scope: correct the strict client response contract that rejects a server-successful agent configuration. - Active constraints: do not bypass validation or enable editing without a real configuration plus revision; do not expose raw prompt/response data. - Decisions affecting this task: one account maps to one Xiaozhi binding; agents/devices are subordinate resources; Main owns auth, idempotency, and ETag conversion. - Evidence, reflections, or commitments affecting this task: production logs prove both upstream and Works endpoints return 200, numeric revision, and a complete field inventory. A local Electron diagnostic using the existing OS-encrypted session fetched the deployed Works endpoint without printing secrets or configuration values and confirmed `content-encoding`, `ETag: W/"0"`, `config_revision: 0`, `chat_history_conf: 0`, and the exact expected snake_case key set. Real deployment smoke remains necessary after the client fix. - Files or modules likely involved: `electron/api/routes/ai-hardware.ts`, `src/lib/ai-hardware.ts`, and their focused tests. - Unknowns, stale docs, or conflicts: the exact edge component that weakens the origin's strong ETag while compressing the response is not represented in this repository. The client can safely recover the numeric application revision from a strictly canonical weak tag only when it matches the typed DTO revision; no canonical memory conflict was found. Gate result: - Passed. ## Outcome - Confirmed the deployed Works Square response was not the same as the origin-hop log: the JSON DTO and numeric revision were valid, while response compression changed the version validator to canonical weak `ETag: W/"0"`. - Updated the Electron Main AI hardware route to accept either canonical strong `"n"` or canonical weak `W/"n"` revision tags. Noncanonical values, negative/decimal values, leading zeroes, non-numeric values, and unsafe integers remain rejected. - Preserved optimistic concurrency: the parsed ETag revision must equal the strictly projected DTO revision, and PATCH/PUT continue to send a strong `If-Match: "n"` header. - Added regression coverage across configuration GET/PATCH and assignment GET/PUT, including weak-tag mismatch and invalid-tag rejection. ## Verification - TDD red: the new deployed-shape cases failed before the implementation with `AI_HARDWARE_INVALID_ETAG` (`2 failed, 23 passed`). - TDD green: `tests/unit/ai-hardware-routes.test.ts` passed `25/25`. - Integrated focused suite passed `7 files / 78 tests`: - `tests/unit/ai-hardware-routes.test.ts` - `tests/unit/ai-hardware-api.test.ts` - `tests/unit/ai-hardware-page.test.tsx` - `tests/unit/host-api-proxy.test.ts` - `tests/unit/ai-hardware-server-registration.test.ts` - `tests/unit/module-navigation.test.tsx` - `tests/unit/main-layout-module-gate.test.tsx` - `corepack pnpm run typecheck` passed. - ESLint passed for both changed TypeScript files. - `git diff --check` passed; Git emitted only line-ending conversion warnings. - Final read-only Sol reviewer returned `PASS` after independently checking the diff and rerunning the 7-file/78-test suite, typecheck, ESLint, doc drift, and registry doctor. ## Follow-ups - Rebuild/redeploy Makelore and repeat the real signed-in Robot configuration read/edit flow through the compressed public Works Square endpoint. - The exact edge component responsible for the strong-to-weak ETag transformation is outside this repository; retaining this strict compatibility prevents future compression changes from breaking the semantic revision flow. ## Promotion Candidates - Target: AI hardware client contract documentation. Proposal: record that versioned Works responses may arrive with canonical weak numeric ETags after content transformation; Electron Main normalizes only the numeric application revision, requires DTO equality, and always emits strong `If-Match` for mutations. Evidence: deployed response `ETag: W/"0"` with `content-encoding` and matching `config_revision: 0`. Future impact: preserves Robot read/edit behavior across compression gateways without weakening optimistic concurrency. Semantic conflicts: original strict strong-response assumption. Human confirmation required: no; this is an observed transport compatibility fact.