Quark Protocol — Spec v1.0

Quark is a streaming-first protocol for connecting AI agents (LLM clients) to tools (tool servers). It replaces Model Context Protocol (MCP) where MCP cracks under production load: composition, streaming, subscriptions, backpressure, capability security, and multi-agent — all built into the protocol, not bolted on.

Anthropic shipped MCP in 2024 and it became the de-facto standard for AI tooling. Technically it is JSON-RPC over stdio/SSE, designed for a desktop-app world. Production workloads expose architectural cracks:

• ✗ No native streaming

  Long-running tool calls (LLM streams, file uploads, log tails) are SSE workarounds.

• ✗ Stateless per call

  Every tool invocation rebuilds context. Burns tokens, multiplies latency.

• ✗ No composition

  "Get repos → filter → summarize → post to Slack" — N round-trips, each with full payload.

• ✗ No subscriptions

  Reactive flows (notify on new PR) need external poll loops.

• ✗ No backpressure

  A flood of requests can DoS a tool server with no graceful degradation.

• ✗ No multi-agent

  Agent-to-agent comms (Claude → Gemini) require bespoke bridges.

• ✗ No capability model

  Tools can do anything. Clients can't restrict.

These aren't bugs — they're consequences of choosing JSON-RPC as the substrate. Fixing them requires a new protocol. Quark is that protocol.

Quark uses WebSocket as the primary transport. WebSocket gives bidirectional streaming, runs in every browser and server, and survives mobile network handovers.

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

For server-to-server federation, plain TCP with the same framing is allowed for lower overhead. Optional QUIC support is reserved for future versions (v0.3+).

Every message on the wire is a 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 are used. Binary frames are reserved for future binary payload (MessagePack option in v0.2).

channel is a persistent stateful connection between a client (AI agent) and a Quark server. Opened on connect, closed on disconnect.

Within a channel, state is preserved:

• Capability grants (valid for channel lifetime or until revoked)
• Subscriptions (active until explicitly unsubscribed or channel closed)
• Open tool streams (alive until completed or cancelled)

A single channel can carry multiple simultaneous calls, streams, and subscriptions, distinguished by seq.

Quark v0.2 introduces cryptographically signed capability tokens — Quark Capability Tokens (QCT). JWT-like, but spec-defined for 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" }
}

▸ client → server

▸ server → client

Every channel starts with a 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
}

If versions don't match, server replies with ERR and closes.

Both sides exchange heartbeats to detect dead connections (firewall timeouts, mobile NAT drops).

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

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

After disconnect (drop, mobile sleep), client reconnects and sends RSM:

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

Server:

• If session valid — replays buffered frames with seq > 42, then resumes
• If expired — ERR { code: "SESSION_EXPIRED" }, client falls back to fresh HEY

Subscriptions and capability grants survive resume. Open tool streams are cancelled (clients should re-INV if needed).

Servers MUST buffer the last 64 outgoing frames per session.

Tools are registered server-side at startup. Clients discover via 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 use JSON Schema Draft 2020-12 with two extensions:

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

This is Quark's killer feature vs MCP.

A single INV can describe a pipeline. The server executes the whole pipeline, only sending the final result back. No round-trips between steps.

{
  "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" } }
  ]
}

Stages:

• tool — invoke a tool, output flows to next stage
• filter — CEL/SQL-like expression filtering items
• map — project fields
• reduce — aggregate
• input_bind — bind previous stage output into the next tool's input

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

Server replies with RES (subscription id), then streams EVT:

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

Until client sends UNS with same seq, or channel closes.

When server is overloaded, it sends WIN with a smaller window. Client MUST not send more than window outstanding requests.

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

Default window: 64. Server can shrink any time. Client must respect.

Quark v0.1 ships a minimal capability model. Capabilities are strings declared by tools and granted by users.

Tool declares: requires_capability: "github:write:repo:foo/bar"

Client (after user consent) in HEY:

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

Server validates capability against granted set on each INV. If missing, returns ERR with code MISSING_CAPABILITY. v0.2 will add cryptographically signed grants for audit/compliance.

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

Standard error codes:

Every frame may include W3C Trace Context metadata:

{
  "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 с родителем

Server propagates trace_id to child operations (pipeline stages, federation). OpenTelemetry collectors can ingest Quark traces via a sidecar that reads frames and emits spans.

Quark ships with an MCP-Quark adapter. Any existing MCP server can be wrapped:

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

The adapter:

• Converts Quark INV → MCP tools/call
• Converts MCP responses → Quark RES
• Loses streaming/composition/subscriptions (MCP doesn't support)
• Logs a warning when advanced feature is requested

This means zero migration cost. Clients start using Quark, existing MCPs continue to work via the adapter, authors migrate to native Quark when they want the new features.

Provided in this repository:

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 for browser-to-browser AI agents
6. v1.3Q1 2027WASM pipeline stages (sandboxed user code)
7. v2.0Q3 2027Asymmetric QCT signing (RSA/ECDSA), full CEL adoption, capability delegation chains