# mosaic-queue

Valkey/Redis-backed task queue with:

- Atomic task lifecycle operations (`claim`, `release`, `heartbeat`, `complete`, `fail`)
- CLI commands for queue management
- MCP server tools for agent integrations

## Requirements

- Node.js `>=20`
- pnpm `10.x`
- Valkey/Redis URL in one of:
  - `VALKEY_URL`
  - `REDIS_URL`

No default Redis URL is hardcoded. Startup fails loudly when neither env var exists.

## Install

```bash
pnpm install
pnpm build
```

## CLI Usage

The package ships a `mosaic` binary.

```bash
mosaic queue create <project> <mission> <taskId> --title "..." [--priority high] [--lane coding]
mosaic queue list [--project X] [--mission Y] [--status pending]
mosaic queue show <taskId>
mosaic queue claim <taskId> --agent <agentId> --ttl 3600
mosaic queue release <taskId> [--agent <agentId>]
mosaic queue complete <taskId> [--agent <agentId>] [--summary "..."]
```

Example:

```bash
export VALKEY_URL="redis://localhost:6379"
mosaic queue create queue phase1 MQ-001 --title "Implement core queue"
mosaic queue claim MQ-001 --agent codex --ttl 3600
```

## MCP Server

The package also ships a `mosaic-queue-mcp` binary exposing:

- `queue_list`
- `queue_get`
- `queue_claim`
- `queue_heartbeat`
- `queue_release`
- `queue_complete`
- `queue_fail`
- `queue_status`

Run over stdio:

```bash
export VALKEY_URL="redis://localhost:6379"
mosaic-queue-mcp
```

## Development

```bash
pnpm lint
pnpm test
pnpm build
```

## Publish Prep

`packages/queue/package.json` includes:

- `bin` entries for `mosaic` and `mosaic-queue-mcp`
- `exports` + `types` for ESM package consumption
- `prepublishOnly` quality gate (`lint`, `test`, `build`)
- `publishConfig.access = public`