Agent Skills
› NeverSight/learn-skills.dev
› hexallabs-sse-contract
hexallabs-sse-contract
GitHub定义HexalLabs统一SSE事件协议，规范POST /api/query接口的请求体及session、token等13种事件结构。适用于Oracle、Council、Relay、Workflow四种模式，确保前端单一消费端兼容不同后端模式的流式输出与心跳机制。
Trigger Scenarios
新增或修改SSE流式接口
实现Oracle/Council/Relay/Workflow模式的后端逻辑
Install
npx skills add NeverSight/learn-skills.dev --skill hexallabs-sse-contract -g -y
SKILL.md
Frontmatter
{
"name": "hexallabs-sse-contract",
"description": "Locked SSE event schema for HexalLabs streaming. Invoke when adding or modifying any SSE endpoint (Oracle, Council, Relay, Workflow). All modes emit same event types so frontend has one consumer."
}
HexalLabs SSE Contract
Endpoint
POST /api/query → text/event-stream
Request body:
{
"mode": "council" | "oracle" | "relay" | "workflow",
"query": "string",
"models": ["Apex", "Swift", ...], // council/oracle
"relay_chain": ["Swift", "Depth"], // relay only
"workflow_nodes": [...], // workflow only
"primal_protocol": false,
"scout": false
}
Event schema
Every event has: event: <type> + data: <json>.
| Event | Emitter | Data shape |
|---|---|---|
session |
backend start | {"session_id": "uuid", "mode": "council"} |
prompt_forge |
Prompt Forge | {"rewritten": "...", "original": "..."} |
hex_start |
per model | {"hex": "Apex"} |
token |
per model stream | {"hex": "Apex", "delta": "text"} |
confidence |
per model self-rate | {"hex": "Apex", "score": 8.5, "stage": "initial" | "rescored"} |
peer_review |
per critique | {"from": "Swift", "to": "Depth", "critique": "..."} |
hex_done |
per model end | {"hex": "Apex", "tokens": 1234, "cached_tokens": 890} |
synth_start |
Apex synth begin | {} |
synth_token |
Apex synth stream | {"delta": "text"} |
synth_done |
Apex synth end | {"final": "full text"} |
lens |
Prompt Lens post-run | {"interpretations": [{"hex": "Swift", "read_as": "..."}]} |
primal |
Primal rewrite | {"delta": "text"} or {"final": "..."} |
done |
session end | {"session_id": "uuid", "duration_ms": 1234} |
error |
fatal | {"hex": "Apex" | null, "code": "string", "message": "..."} |
Rules
- Always emit
sessionfirst,donelast. hexfield uses white-label only (see hexal-whitelabel-names skill).tokenandsynth_tokenare deltas, not cumulative. Frontend concatenates.- Order not guaranteed across hexes (parallel streams). Frontend buffers per
hex. - Relay mode emits
hex_donefor model 1 thenhex_startfor model 2 w/ handoff context; still uses same events. - Workflow mode emits same events per node; add
node_idtohex_start/done. - Oracle = skip
peer_reviewandsynth_*.tokenstream from single hex →done. - Heartbeat: send
: keep-alive\n\ncomment every 15s if no events.
Example stream (Council, 2 models)
event: session
data: {"session_id":"abc","mode":"council"}
event: hex_start
data: {"hex":"Swift"}
event: hex_start
data: {"hex":"Depth"}
event: token
data: {"hex":"Swift","delta":"Hello"}
event: token
data: {"hex":"Depth","delta":"Analysis:"}
event: confidence
data: {"hex":"Swift","score":7,"stage":"initial"}
event: hex_done
data: {"hex":"Swift","tokens":120,"cached_tokens":0}
event: peer_review
data: {"from":"Swift","to":"Depth","critique":"Shallow on step 3"}
event: confidence
data: {"hex":"Depth","score":9,"stage":"rescored"}
event: synth_start
data: {}
event: synth_token
data: {"delta":"Final:"}
event: synth_done
data: {"final":"Final answer..."}
event: done
data: {"session_id":"abc","duration_ms":4321}
Do not change without migration
Frontend consumer = single parser. Any event rename breaks hex grid. Add new events, don't rename.
Version History
- e0220ca Current 2026-07-05 21:34
