# Synadia NATS Agents

Open console · YouTrack and Codex await configuration

Synadia console in Vue/Bun, a YouTrack gateway and a separate Codex worker, connected through NATS JetStream. Discovery and diagnostic chat are connected. Running YouTrack tasks still needs access configuration.

Source version: `d5b786da3c0477027db48a5d0abe4676b67a0ba5`

Repository history: since 22 May 2026. Published version: 7 September 2026.

[Project notes](https://portfolio.komaroff-dev.ru/en/projects/agents/) · [Online documentation](https://portfolio.komaroff-dev.ru/en/projects/agents/docs/)

[Demo](https://agents.komaroff-dev.ru/)

[Source repository](https://github.com/komaroffsergei/nats-synadia-dev)

## Task

A job can take longer than an HTTP request. The gateway puts it in a queue and a worker processes it separately. It needs redelivery and a check against applying a completed result twice.

Processing issue tracker tasks through a queue and workers.

## Work done

- Webhook → JetStream → worker → result flow.
- Durable consumer, ACK/NAK, redelivery and completed-job checks.
- Console and worker deployment, discovery and diagnostic chat checks.

## Stack

| Technology | Role |
| --- | --- |
| Vue / Bun | Original Synadia interface and WebSocket bridge |
| NATS / JetStream | Discovery, queue and durable consumers |
| Node.js / Codex SDK | Separate worker |
| MCP / REST | YouTrack after access configuration |

## Architecture and decisions

- The original examples/agent-web-ui is served by Bun; scripts/start-production.js starts the processes.
- The gateway handles webhooks and results; the worker is separate from HTTP and reads a JetStream durable consumer.
- A separate NATS account is used; subjects youtrack.codex.jobs.komaroff and youtrack.codex.results.komaroff belong to stream KOMAROFF_CODEX.
- CODEX_DRY_RUN=false and YOUTRACK_DRY_RUN=false. Missing credentials are not replaced with synthetic responses.
- The console has been open without a password since 7 September 2026. The webhook requires its own token; NATS and the database are not exposed publicly.

### Components and integration boundaries

![Components and integration boundaries](https://portfolio.komaroff-dev.ru/evidence/agents/revision-d5b786da/diagrams/components.svg)

[Mermaid source](https://portfolio.komaroff-dev.ru/evidence/agents/revision-d5b786da/diagrams/components.mmd)

### Verified diagnostic request

![Verified diagnostic request](https://portfolio.komaroff-dev.ru/evidence/agents/revision-d5b786da/diagrams/sequence.svg)

[Mermaid source](https://portfolio.komaroff-dev.ru/evidence/agents/revision-d5b786da/diagrams/sequence.mmd)

### Deployment

![Deployment](https://portfolio.komaroff-dev.ru/evidence/agents/revision-d5b786da/diagrams/deployment.svg)

[Mermaid source](https://portfolio.komaroff-dev.ru/evidence/agents/revision-d5b786da/diagrams/deployment.mmd)

## Code map

| Feature | Screen / API | Module | Data / verification |
| --- | --- | --- | --- |
| Console | / and /ws | examples/agent-web-ui/server/index.ts; server/bridge.ts | Vue/Bun, WebSocket, Synadia discovery; UI and health response checked |
| Webhook | /youtrack/webhook | src/youtrack-gateway.js | token validation, quick job enqueueing |
| Queue | KOMAROFF_CODEX | src/jetstream.js | durable worker, results, readiness |
| Execution | Codex worker | src/codex-worker.js; scripts/acodex | sequential execution; awaiting a key |
| YouTrack | MCP or REST | src/youtrack-mcp-client.js; youtrack-gateway.js | external access is not yet configured |

Before changing a feature, trace its interface, API, state and storage dependencies. Check inputs, errors, retries and related workflows. Update the map and affected diagrams alongside the code, rerun the related checks and attach evidence for the source version.

## Workflows and API

1. Open the console without signing in; check CONNECTED and the discovered codex NATS agent.
2. Open the agent, send health and receive a real response about JetStream, subjects and consumers.
3. After configuring YouTrack and Codex: webhook → job → separate worker → result → write the result to YouTrack.
4. Check job states, results, redelivery and worker recovery using an agreed test task.

## Verification

- The full original image was built in GitHub CI. The API and separate worker are running.
- Synadia UI discovered one real agent; health passed through WebSocket/NATS and returned the state of KOMAROFF_CODEX.
- Both dry-run flags are disabled; NATS and consumer readiness are confirmed.
- Unauthenticated access and webhooks without a token were rejected. Desktop and mobile views were checked.
- No real Codex task or YouTrack write was performed: integration configuration is missing.

[CI: Full build of the original application](https://github.com/komaroffsergei/nats-synadia-dev/actions/runs/34082306471) — `d5b786da3c0477027db48a5d0abe4676b67a0ba5`, 2026-09-07; this demo's version.

## Results and measurements

- Five sequential HTTPS GET requests from the VPS to itself: 8.9–60.7 ms, all HTTP 200. This is not a load test or an assessment of the external network.
- No Telegram collection, LLM processing or Codex task ran during the measurements.

These checks apply to the listed version. Business metrics and model quality on an independent dataset were not measured.

![Container memory: three snapshots without external processing](https://portfolio.komaroff-dev.ru/evidence/agents/revision-d5b786da/metrics/resources.svg)

[Container memory: three snapshots without external processing: source data](https://portfolio.komaroff-dev.ru/evidence/agents/revision-d5b786da/metrics/resources.json)

## Limitations

- The YouTrack URL and MCP/REST access are not configured. An unreachable placeholder replaces the corporate URL; no requests are sent to the production YouTrack service.
- Codex/OpenAI access has not yet been provided. Task execution and posting comments to YouTrack have not been verified.
- Diagnostic health/hooks/jobs responses come from the gateway, not an LLM.
- Discovery and gateway diagnostics are public. Current Codex Desktop tasks and subagents are not yet connected to the console.

## Running and operating

The full image uses the original docker/Dockerfile. App: node scripts/start-production.js; worker: node src/codex-worker.js.

Settings: /srv/portfolio/agents/.env and integrations.env; separate persistent codex-state. Docker resources and logs are limited.

YOUTRACK_BASE_URL and YOUTRACK_MCP_URL or YOUTRACK_TOKEN are required; model access requires the agreed OPENAI_API_KEY/CODEX_API_KEY or another supported method. Do not transfer corporate credentials without the owner's instruction.

Once configured, verify one explicitly selected task: webhook, durable job, session_started, analysis_completed and the result in YouTrack. Until then, this chain remains unverified.

## Screenshot index

1. [Original Synadia console and real discovery](https://portfolio.komaroff-dev.ru/evidence/agents/revision-d5b786da/full/01-original-ui.png) — 2026-09-07T04:30:21.811784+00:00, source `d5b786da3c0477027db48a5d0abe4676b67a0ba5`.

2. [Discovered agent details](https://portfolio.komaroff-dev.ru/evidence/agents/revision-d5b786da/full/02-agent.png) — 2026-09-07T04:30:21.983358+00:00, source `d5b786da3c0477027db48a5d0abe4676b67a0ba5`.

3. [Health response through the real NATS bus](https://portfolio.komaroff-dev.ru/evidence/agents/revision-d5b786da/full/03-real-nats-response.png) — 2026-09-07T04:30:22.195529+00:00, source `d5b786da3c0477027db48a5d0abe4676b67a0ba5`.

4. [Mobile Synadia console](https://portfolio.komaroff-dev.ru/evidence/agents/revision-d5b786da/full/04-mobile.png) — 2026-09-07T04:30:22.306011+00:00, source `d5b786da3c0477027db48a5d0abe4676b67a0ba5`.

Screenshots, diagrams and the original evidence package retain their source language. Captions and this document are translated into English.

[Original evidence package](https://portfolio.komaroff-dev.ru/evidence/agents/revision-d5b786da/materials.zip)