adom-vscode queue push login --type refresh-needed --payload '{"expiresInHours":24}'
adom-vscode queue push progress --type job-progress --payload '{"job":"bake","pct":40}' --ttl 120
adom-vscode queue pull --topic login          # consume matching events (removes them)
adom-vscode queue pull --peek                 # read WITHOUT consuming
adom-vscode queue pull --max 10               # cap a batch
adom-vscode queue status                      # depth + per-topic counts
adom-vscode queue clear --topic progress      # drop one topic (or everything without --topic)

---
name: adom-vscode-queue
description: "The shared event queue between container processes and the Hydrogen Desktop / Hydrogen Web frontend, hosted by the adom-vscode extension. Any process pushes events (login refresh needed, long-job progress, arbitrary payloads); the frontend pulls when it wants. Survives window reloads. Trigger words: event queue, queue push, queue pull, push event to frontend, notify hd frontend, frontend event, progress dialog event, api key expiring event, login refresh event, queue status, queue peek, queue topic, adom-vscode queue, POST /queue/push, pull events."
---

Parent skill: **adom-vscode**

# adom-vscode-queue, container-to-frontend events

A simple durable FIFO inside the extension. Producers are anything in the
container (a watcher, a build, an AI thread); the consumer is usually the HD/HW
frontend polling when it cares. Events survive VS Code window reloads
(persisted to `~/.local/share/adom-vscode/queue.json`), are capped at 1000
items, and can carry a per-item TTL.

## Verbs

```bash
adom-vscode queue push login --type refresh-needed --payload '{"expiresInHours":24}'
adom-vscode queue push progress --type job-progress --payload '{"job":"bake","pct":40}' --ttl 120
adom-vscode queue pull --topic login          # consume matching events (removes them)
adom-vscode queue pull --peek                 # read WITHOUT consuming
adom-vscode queue pull --max 10               # cap a batch
adom-vscode queue status                      # depth + per-topic counts
adom-vscode queue clear --topic progress      # drop one topic (or everything without --topic)
```

HTTP: `POST /queue/push {topic?, type?, payload?, ttlSec?}` returns `{id, depth}`;
`GET/POST /queue/pull {topic?, max?, peek?}` returns `{items, count, remaining}`;
`GET /queue/status`; `POST /queue/clear {topic?}`.

Each item: `{id, ts, topic, type, payload, ttlSec}`. Default topic is
`default`, default type is `event`. Expired items vanish on the next access.

## Patterns

- **Login refresh**: NOTE, adom-vscode ships NO built-in key watcher; this is
  the pattern for whichever process owns key freshness (an HD daemon, a cron
  job, any container process). That process decides its own cadence, notices
  the session key in `/var/run/adom/api-key` is close to expiry, and pushes
  `topic: login, type: refresh-needed`; the frontend pulls, shows the "needs a
  login refresh" banner, refreshes, then injects the new key (see
  **adom-vscode-container** for `apikey set`).
- **Progress dialog**: a long container job pushes `topic: progress` events with
  a TTL a bit above the push interval, so stale progress self-cleans if the
  frontend never pulls.
- **Peek before consume**: a frontend that only renders a badge should
  `--peek`; consume (`pull` without peek) only when the event is handled, so a
  crashed frontend does not eat events.

## Semantics worth knowing

- Pull REMOVES what it returns (unless `peek`). Two consumers splitting one
  topic will race; give each its own topic.
- Depth is bounded at 1000: oldest items drop first past the cap.
- The queue is per-container and in one extension host; a window reload reloads
  it from disk, so nothing is lost across reloads.