> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scomp.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> What the scomp protocol does, what it doesn't, and how the pieces fit together.

The scomp protocol governs **one wire**: the messages exchanged between a client peer (typically an agent's harness) and a server peer (typically a runtime host). It's a thin layer on top of JSON-RPC 2.0 and a bidirectional transport.

This page is the 30,000-foot view. The pages that follow drill in.

## What scomp does

The protocol does **two things, and only two**:

<Steps>
  <Step title="Negotiates a session">
    The client opens a transport connection and sends a `handshake` request declaring its protocol version, its client-declared bindings, and optional metadata (auth, identity). The server responds with its protocol version, its server-declared bindings, and a `sessionId`. Sessions outlive connections.
  </Step>

  <Step title="Carries eval and invoke">
    After the handshake, the client can submit code for evaluation. Either peer can invoke the other's bindings or function references, at any time, in any direction. That's the entire steady-state vocabulary.
  </Step>
</Steps>

Everything above that — agent loops, prompt construction, tool selection, persistent-state conventions, multi-agent orchestration, UI patterns — lives in harnesses and SDKs, not the protocol.

## What scomp doesn't do

Equally important: the things the protocol deliberately stays out of.

<CardGroup cols={2}>
  <Card title="Not a tool-calling protocol" icon="x">
    Complementary to MCP. MCP exposes individually-callable tools to a stateless loop; scomp projects an agent into a stateful programmable environment. The two compose.
  </Card>

  <Card title="No runtime spec" icon="x">
    QuickJS is the reference runtime, but Lua, Rhai, Wasm, or anything else that accepts code and produces JSON-serializable results conforms equally.
  </Card>

  <Card title="No transport spec" icon="x">
    WebSocket is blessed for v0.1 interoperability. Any bidirectional, message-oriented, in-order transport satisfies the abstract contract.
  </Card>

  <Card title="No harness opinions" icon="x">
    How agents author code, how harnesses build prompts, how application logic is organized — all out of scope. The protocol is the wire; opinions go above it.
  </Card>
</CardGroup>

## The stack

Scomp distinguishes five layers. Two of them are protocol-bearing; the other three are implementation-defined.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vesper"}}
flowchart TB
    A["Agent (LLM)<br/><i>Reasons, writes code</i>"]
    H["Harness<br/><i>Drives the loop, builds prompts</i>"]
    C["Client SDK"]
    S["Server SDK"]
    R["Runtime + bindings<br/><i>Evaluates code, hosts state</i>"]

    A -- "free-form generation" --> H
    H -- "SDK calls" --> C
    C <-. "scomp protocol" .-> S
    S -- "binding invocations" --> R
```

The dashed line is the protocol. Everything else is convention between the layers a single implementation owns. An SDK can be thin (a transport binding + types) or fat (a full harness loop), and either conforms.

## Why this shape

Three design choices shape almost everything else.

**JSON-RPC 2.0** as the framing layer. Universal library support, standardized error model, bidirectional symmetry, unambiguous wire. The cost is essentially zero; the benefit is that any language can implement scomp with off-the-shelf parsing.

**Protocol-symmetric peers.** Both sides declare bindings using the same metadata shape. Either side can invoke by name. The asymmetry is in *who calls what*, not in *what is described*. SDKs share types between client and server; spec stays small.

**Runtime-agnostic at the wire.** A C→S `invoke` routes at the JSON-RPC layer, not by building runtime-specific source strings (`await binding({...})` for JS, different syntax for Lua, …). The protocol layer is the abstraction point; the runtime is interchangeable.

## Sub-pages

<CardGroup cols={2}>
  <Card title="Architecture" icon="layers" href="/protocol/architecture">
    The five-layer model in depth, plus the rationale for runtime-agnosticism.
  </Card>

  <Card title="Wire format" icon="terminal" href="/protocol/wire-format">
    JSON-RPC framing, transport requirements, worked req/resp examples.
  </Card>

  <Card title="Lifecycle" icon="git-branch" href="https://github.com/scomp-protocol/scomp/blob/master/PROTOCOL.md#4-lifecycle">
    Connection → handshake → steady state → close. Concurrency rules. (§4 of `PROTOCOL.md`)
  </Card>

  <Card title="Bindings" icon="puzzle" href="https://github.com/scomp-protocol/scomp/blob/master/PROTOCOL.md#5-bindings">
    Binding metadata, JSON Schema requirements, effects, hints. (§5 of `PROTOCOL.md`)
  </Card>

  <Card title="Function references" icon="arrows-up-from-line" href="https://github.com/scomp-protocol/scomp/blob/master/PROTOCOL.md#9-function-references">
    Passing callables across the wire — the `$scomp.fn` sentinel and its lifecycle. (§9 of `PROTOCOL.md`)
  </Card>

  <Card title="Sessions" icon="rotate-cw" href="https://github.com/scomp-protocol/scomp/blob/master/PROTOCOL.md#7-sessions">
    What persists across reconnects, and what doesn't. (§7 of `PROTOCOL.md`)
  </Card>

  <Card title="Errors" icon="circle-alert" href="https://github.com/scomp-protocol/scomp/blob/master/PROTOCOL.md#10-errors">
    JSON-RPC codes, scomp-specific codes, structured error data. (§10 of `PROTOCOL.md`)
  </Card>
</CardGroup>

<Tip>
  The canonical, normative spec lives at [`PROTOCOL.md`](https://github.com/scomp-protocol/scomp/blob/master/PROTOCOL.md) in the repo. These pages are docs-site reading material — narrative, worked examples, diagrams. When wording matters (MUST vs SHOULD), `PROTOCOL.md` is the source of truth.
</Tip>