Wire Protocol & Rule Specification

ContextShim Technical Reference

Complete wire grammar for all 4 emulated LLM protocols, predicate matching semantics, SSE streaming frames, BYOK upstream routing headers, and Streamable HTTP MCP tools.

1. Four Native Emulated LLM Wire Endpoints

ContextShim speaks the exact wire envelopes expected by official OpenAI, Anthropic, and Cloud Ollama SDKs:

Endpoint	Protocol	JSON Envelope	Stream Format (`stream: true`)
`POST /v1/chat/completions`	OpenAI Chat	`chat.completion`	SSE `data: {...}` + `data: [DONE]`
`GET /v1/models`	OpenAI Models	`{ object: "list", data: [...] }`	N/A
`POST /v1/messages`	Anthropic Messages	`{ type: "message", content: [...] }`	SSE `event: message_start ... message_stop`
`POST /v1/responses`	OpenAI Responses	`{ object: "response", output_text }`	SSE `event: response.output_text.delta`
`POST /api/chat` & `/api/generate`	Cloud Ollama	`{ model, message/response, done: true }`	NDJSON lines (or SSE with `Accept: text/event-stream`)

2. Rule Predicate Grammar & Evaluation Priority

Rules are evaluated in descending priority order (ties broken lexicographically by id). If any matched rule has mode respond_directly, the highest-priority match synthesizes the response immediately with 0 upstream tokens. Otherwise, all matching inject_context rules apply in priority order before upstream forwarding.

Rule JSON Schema

{
  "id": "rule-coding-standards",
  "name": "Repository Engineering Standards Injector",
  "mode": "inject_context",
  "priority": 70,
  "enabled": true,
  "expected_version": 1,
  "predicates": {
    "regex": "implement|refactor",
    "keyword_any": ["typescript", "javascript", "python"],
    "model_glob": "*",
    "header_match": { "x-env": "prod*" },
    "path": ["/v1/chat/completions", "/v1/messages"],
    "role_scope": "user",
    "project_tag": "checkout-api"
  },
  "action": {
    "system_prepend": "Enforce strict ESM and parameterized SQL.",
    "system_append": "Tag verified code responses with [CSHIM-STD].",
    "user_prepend": "",
    "user_append": ""
  }
}

3. Context Injection Slots & Template Interpolation

Templates in response_template, system_prepend, system_append, user_prepend, and user_append support inline variables: {{model}}, {{protocol}}, {{wire_path}}, {{project_tag}}, {{rule_id}}, and {{timestamp}}.

4. SSE & NDJSON Streaming Compatibility

When callers pass "stream": true, ContextShim streams native protocol frames while still attaching x-contextshim-mode, x-contextshim-rules-matched, x-contextshim-tokens-saved, and x-contextshim-trace-id HTTP response headers on the initial 200 OK header frame.

5. BYOK & Cloud Ollama Upstream Headers

By default, sandbox calls route to Cloud Ollama (https://ollama.com/v1). Override the upstream provider per-request using standard headers:

BYOK Upstream Routing

curl -sS https://contextshim.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-contextshim-key: cshim_live_your_key" \
  -H "x-upstream-provider: ollama" \
  -H "x-contextshim-project: core-api" \
  -d '{"model":"glm-5.3-flash","messages":[{"role":"user","content":"contextshim:ping"}]}'

Supported x-upstream-provider values: ollama (https://ollama.com/v1), openai (https://api.openai.com/v1), anthropic (https://api.anthropic.com/v1), gemini (https://generativelanguage.googleapis.com/v1beta/openai), and openrouter (https://openrouter.ai/api/v1), or any public HTTPS endpoint via x-upstream-url + x-upstream-key.

6. Management REST API & Streamable HTTP MCP

GET /api/v1/rules & POST /api/v1/rules: List and CAS-upsert rules via expected_version (returns 409 Conflict on stale version).
POST /api/v1/simulate: Dry-run or live Cloud Ollama simulation returning wire_diff and receipt headers.
GET /api/v1/traces: Query redacted wire traces and SHA-256 digests.
POST /api/v1/keys/mint: Mint a self-serve cshim_live_* API key.
POST /mcp & GET /mcp: Streamable HTTP MCP server exposing contextshim_list_rules, contextshim_upsert_rule, contextshim_simulate, contextshim_list_traces, and contextshim_mint_key.