Quark Protocol — Spec v1.0

Quark — это streaming-first протокол для соединения AI-агентов (LLM-клиентов) с инструментами (tool servers). Он заменяет Model Context Protocol (MCP) в production-сценариях где MCP даёт сбой: композиция, стриминг, подписки, backpressure, capability-based security и multi-agent — встроены в протокол, а не сделаны костылями поверх.

MCP от Anthropic шипнул в 2024 и стал де-факто стандартом для AI-tooling. Технически — это JSON-RPC поверх stdio/SSE, спроектированный для desktop-app мира. На production-нагрузках видны архитектурные трещины:

• ✗ Нет нативного стриминга

  Long-running tool calls (LLM-стримы, file uploads, log tails) — через SSE-костыли.

• ✗ Stateless каждый call

  Каждый tool invocation пересоздаёт контекст. Жжёт токены, увеличивает latency.

• ✗ Нет композиции

  "Get repos → filter → summarize → post to Slack" — N round-trips с полным payload.

• ✗ Нет подписок

  Реактивные workflow (notify on new PR) — внешние poll-loops.

• ✗ Нет backpressure

  Поток запросов может DoS-нуть tool server. Нет graceful degradation.

• ✗ Нет multi-agent

  Agent-to-agent (Claude → Gemini) требует кастомных мостов.

• ✗ Нет capability model

  Tool может делать что угодно. Клиент не может ограничить.

Это не баги, а следствия выбора JSON-RPC как подложки. Чтобы починить — нужен новый протокол. Quark — это он.

Quark использует WebSocket как основной транспорт. WebSocket даёт двунаправленный стриминг, работает в каждом браузере и на любом сервере, переживает mobile-network handovers.

ws://server:port/quark
wss://server:port/quark   (TLS, recommended)

Для server-to-server federation допустим plain TCP с тем же framing — меньше overhead. Опциональный QUIC резервируется для v0.3+.

Каждое сообщение в линии — это frame: 4-байтовый header + JSON payload.

┌─────────┬─────────┬─────────────────────────────┐
│ version │  kind   │       payload (JSON)        │
│ 1 byte  │ 3 bytes │       variable length       │
└─────────┴─────────┴─────────────────────────────┘

• version — версия протокола, сейчас 0x01
• kind — 3-буквенный ASCII opcode (см. ниже)
• payload — UTF-8 JSON, может быть пустым

WebSocket text-frames используются. Binary-frames зарезервированы для будущей бинарной payload (MessagePack в v0.2).

channel — это persistent stateful соединение между клиентом (AI-агентом) и Quark-сервером. Открывается на connect, закрывается на disconnect.

Внутри канала сохраняется состояние:

• Capability grants (валидны до конца канала или revoke)
• Подписки (живут пока не отписался или канал закрыт)
• Открытые tool-стримы (живы пока не completed или cancelled)

Один канал может нести несколько одновременных вызовов / стримов / подписок, различаемых через seq.

Quark v0.2 ввёл криптографически подписанные capability-токены — Quark Capability Tokens (QCT). Похоже на JWT, но spec-defined для Quark.

qct.v1.<base64url(payload)>.<base64url(signature)>

signature = HMAC-SHA256(secret, "v1." + base64url(payload))

{
  "iss": "https://issuer.example.com",
  "sub": "[email protected]",
  "iat": 1690000000,
  "nbf": 1690000000,
  "exp": 1700000000,
  "scope": ["github:read:*", "slack:notify:#dev"],
  "client_id": "claude-desktop",
  "max_cost_usd": 5.00
}

github:read:*                          # read anything on GitHub
github:write:repo:owner/name           # write to specific repo
slack:notify:#general                  # notify a specific Slack channel
slack:notify:*                         # notify any Slack channel
*:read                                 # read anything anywhere

{
  "kind": "HEY",
  "v": 2,
  "auth": { "type": "bearer", "token": "qct.v1.eyJ..." },
  "agent": { "id": "claude-desktop", "kind": "llm", "name": "Claude" }
}

▸ клиент → сервер

▸ сервер → клиент

Каждый канал стартует с обмена HEY.

{
  "kind": "HEY",
  "v": 1,
  "agent": {
    "id": "claude-desktop-3.7-mac",
    "kind": "llm",
    "name": "Claude Desktop"
  },
  "supports": ["streaming", "subscribe", "compose", "capabilities"]
}

{
  "kind": "HEY",
  "v": 1,
  "server": {
    "id": "github-tools-v2",
    "name": "GitHub Tools",
    "version": "2.1.0"
  },
  "supports": ["streaming", "subscribe", "compose", "capabilities"],
  "tools": 12,
  "topics": 4
}

Если версии не совпадают, сервер отвечает ERR и закрывает канал.

Обе стороны обмениваются heartbeat'ами для определения мёртвых соединений (firewall timeouts, mobile NAT drops).

// Client (every 30s)
{ "kind": "HBT", "ts": 1700000000 }

// Server
{ "kind": "HBA", "ts": 1700000000 }

После disconnect (drop, mobile sleep) клиент переподключается и шлёт RSM:

{
  "kind": "RSM",
  "v": 2,
  "session_id": "ses_a7b3c9d1",
  "last_seq_received": 42
}

Сервер:

• Если session жив — реплеит буферизованные frames с seq > 42, потом продолжает
• Если истёк — ERR { code: "SESSION_EXPIRED" }, клиент fallback на свежий HEY

Subscriptions и capability grants переживают resume. Открытые tool-streams отменяются (клиент должен re-INV если нужно).

Серверы ОБЯЗАНЫ буферизовать последние 64 outgoing frames на сессию.

Инструменты регистрируются на сервере при старте. Клиенты discoverят через LST:

{
  "kind": "LST",
  "seq": 1,
  "tools": [
    {
      "name": "github.list_repos",
      "description": "List repos for a user/org",
      "input": { "type": "object", "properties": { "owner": { "type": "string" } } },
      "output": { "type": "array", "items": { "$ref": "#/types/Repo" } },
      "effects": ["network", "read"],
      "cost": { "estimate": 0.0001, "currency": "USD" },
      "streaming": true,
      "requires_capability": "github:read"
    }
  ]
}

Tool schemas используют JSON Schema Draft 2020-12 с двумя расширениями:

• effects — массив из pure | read | write | network | money | irreversible | cost
• cost — оценённая стоимость вызова (помогает AI бюджетировать)
• requires_capability — capability которая нужна для вызова

Это killer-фича Quark vs MCP.

Один INV может описать pipeline. Сервер выполняет всю цепочку, отправляя клиенту только финальный результат. Никаких round-trips между шагами.

{
  "kind": "INV",
  "seq": 4,
  "pipeline": [
    { "tool": "github.list_repos", "input": { "owner": "anthropic" } },
    { "filter": "stars > 100" },
    { "map": ["name"] },
    { "tool": "slack.notify", "input_bind": { "items": "$prev", "channel": "#dev" } }
  ]
}

Стадии:

• tool — вызов tool, output течёт в следующую стадию
• filter — CEL/SQL-like выражение
• map — проекция полей
• reduce — агрегация
• input_bind — байнд предыдущей output в input следующего tool

{
  "kind": "SUB",
  "seq": 5,
  "topic": "github.pr_opened",
  "filter": { "repo": "anthropic/claude-code" }
}

Сервер отвечает RES с subscription id, потом стримит EVT:

{ "kind": "EVT", "seq": 5, "data": { "pr": 123, "title": "Fix typo" } }

Пока клиент не пошлёт UNS с тем же seq, или канал не закроется.

Когда сервер перегружен, он шлёт WIN с меньшим окном. Клиент НЕ ДОЛЖЕН слать больше чем window outstanding requests.

{ "kind": "WIN", "window": 3 }

Дефолтное окно: 64. Сервер может сжать в любой момент. Клиент обязан respect.

Quark v0.1 ставит минимальную capability model. Capabilities — это строки которые tool декларирует, а юзер grant'ит.

Tool декларирует: requires_capability: "github:write:repo:foo/bar"

Клиент (после согласия юзера) в HEY:

"capabilities": [
  "github:read:*",
  "github:write:repo:foo/bar",
  "slack:notify:#dev"
]

Сервер валидирует capability против granted списка на каждом INV. Если missing — ERR с кодом MISSING_CAPABILITY. В v0.2 будут cryptographically signed grants для audit/compliance.

{
  "kind": "ERR",
  "seq": 4,
  "code": "MISSING_CAPABILITY",
  "message": "Tool github.write_issue requires github:write",
  "stage": 1
}

Стандартные коды ошибок:

Каждый frame может содержать tracing metadata по стандарту W3C Trace Context:

{
  "kind": "INV",
  "seq": 5,
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "parent_span_id": "00f067aa0ba902b1",
  "tool": "github.list_repos"
}

• trace_id — 32 hex chars, идентифицирует distributed trace
• span_id — 16 hex chars, идентифицирует span внутри trace
• parent_span_id — связывает span с родителем

Сервер пропагирует trace_id ко всем child-операциям (pipeline stages, federation). OpenTelemetry collectors могут ingest'ить Quark traces через sidecar который читает frames и emit'ит spans.

Quark поставляется с MCP-Quark adapter. Любой существующий MCP-сервер можно обернуть:

[AI agent] ──Quark──> [Quark adapter] ──MCP──> [legacy MCP server]

Adapter:

• Конвертит Quark INV → MCP tools/call
• Конвертит MCP ответы → Quark RES
• Теряет streaming/composition/subscriptions (MCP не поддерживает)
• Логает warning когда advanced feature запрошен

Это значит zero migration cost. Клиенты начинают использовать Quark, существующие MCPs работают через adapter, авторы мигрируют на native Quark когда захотят новые фичи.

Reference implementations в этом репо:

srv := quark.NewServer()
srv.RegisterTool(quark.Tool{
  Name: "echo.upper",
  Description: "Echo text in uppercase",
  Handler: func(ctx context.Context, in map[string]any) (any, error) {
    return strings.ToUpper(in["text"].(string)), nil
  },
})
http.Handle("/quark/ws", srv)

import { Quark } from '@fasad_salatov/quark-client'

const ch = await Quark.connect('wss://server/quark/ws', {
  agent: { id: 'my-bot', kind: 'llm', name: 'My Bot' },
})

const repos = await ch.invoke('github.list_repos', { owner: 'anthropic' })

for await (const log of ch.stream('logs.tail', { file: 'app.log' })) {
  console.log(log.line)
}

const filtered = await ch.pipeline([
  { tool: 'github.list_repos', input: { owner: 'anthropic' } },
  { filter: 'stars > 100' },
  { map: ['name'] },
])

1. v0.1Apr 2026initial draft, reference impls, MCP adapter
2. v0.2Jun 5, 2026QCT auth, session resume, heartbeat, validation, cost tracking, tracing
3. v1.0Jun 6, 2026stable. Federation, MessagePack, extended filter, schema registry, Python SDK.▸ now
4. v1.1Q3 2026QUIC transport, mesh routing improvements
5. v1.2Q4 2026WebRTC P2P для browser-to-browser AI агентов
6. v1.3Q1 2027WASM pipeline stages (sandboxed user code)
7. v2.0Q3 2027Asymmetric QCT signing (RSA/ECDSA), full CEL adoption, capability delegation chains