Skip to content

Polish: avoid 404 noise when Data Widgets fetch catalogued keys before first poll #41

Description

@sebastientaggart

Summary

Harmless but noisy: OpenDeck Data Widgets call GET /state/{key} on willAppear for keys listed in [catalog.state_keys]. Until the usage poller (e.g. claude_code_usage) successfully publishes those keys, Core returns 404 state not found. The plugin already treats 404 as missing and shows , so UX is fine — access logs just look alarming.

Example after a cold start / failed OAuth poll:

GET /catalog/state_keys → 200
GET /state/usage.claude_code.session → 404
GET /state/usage.claude_code.week → 404
GET /state/usage.claude_code.week_fable → 404

Catalog ≠ live store is intentional (you can bind widgets before the first poll). This ticket is polish only.

Ideas (pick one when implementing)

  1. Seed placeholders — on plugin register / first loop tick, publish the known keys with available: false / title: "—" so GET /state/... is 200 before Anthropic responds.
  2. Catalog-aware GET — if the key is in [catalog.state_keys] but not in the store, return a synthetic empty entry (200) instead of 404.
  3. Docs only — note in README / PLUGIN_GUIDE that 404 until first successful poll is expected; leave API as-is.

Related: optional [paths] state_file already preserves last-known values across restarts and reduces this window.

Acceptance

  • Binding a Data Widget to a catalogued usage key before the first successful poll no longer floods access logs with 404s (or is clearly documented as expected).
  • Widget still shows / updates via state.changed once real values arrive.
  • No change to “unknown key that was never catalogued” behavior unless we explicitly decide otherwise.

Context

Seen while running Deckhand in the foreground with claude_code_usage enabled; also coincided with occasional Anthropic 429 on GET /api/oauth/usage, which delays the first successful set_state.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions