open-sse

Imported from YumamaX3/Vela (open-sse/AGENTS.md). Install upstream with npx skills add YumamaX3/Vela --skill open-sse. Copyright stays with the author.

open-sse

Provider-agnostic SSE engine: one OpenAI-style request → any provider (LLM chat, image, embedding, tts, stt, search), streamed back in the client's format.

Request lifecycle (chat)

handlers/chatCore.js → services/model.js parseModel (resolve provider/model) → pre-translate hooks (rtk/ tool_result compress, rtk/headroom.js proxy compress, rtk/caveman.js system inject — all fail-open) → executors/index.js getExecutor(provider) → translator/index.js translateRequest (client format → provider format) → executor.execute() (streams upstream) → translateResponse (provider chunks → client format) → SSE out.

Directory map

• config/ — ALL constants/config (no hardcode elsewhere). providers.js/registry/ (provider defs), providerModels.js (alias→models matrix), runtimeConfig.js (timeouts, token limits), *Constants.js.
• translator/ — format conversion. request/<from>-to-<to>.js, response/<from>-to-<to>.js, schema/ (enums: ROLE, CLAUDE_BLOCK…), concerns/ (shared logic), formats.js+formats/ (per-format). index.js is the registry/entry.
• executors/ — per-provider upstream call. base.js (BaseExecutor), one file per special provider, index.js map.
• providers/ — registry build + capabilities.js + pricing.js (rate tables — see "Pricing model" below). Entry: index.js (PROVIDERS).
• handlers/ — per-modality cores (chat/image/embedding/tts/stt/search) + sub-provider folders. chatCore/ has the streaming/non-streaming/sse-to-json handlers.
• rtk/ — request token-killer. index.js compresses tool_result content in-place (OpenAI/Claude/Kiro shapes); filters/ per-tool compressors + autodetect.js; headroom.js external compress proxy; caveman.js system-prompt injector.
• transformer/ — responsesTransformer.js (Chat Completions SSE → Codex Responses API SSE), streamToJsonConverter.js.
• shared/ — cross-provider auth/identity: clineAuth.js, machineId.js, qoder/.
• services/ — model.js, provider.js, accountFallback.js, combo.js, compact.js, tokenRefresh/+tokenRefresh.js, oauthCredentialManager.js, usage/, projectId.js, kiroModels.js/qoderModels.js.
• utils/ — streamHandler, stream, sse, error, sessionManager, claudeCloaking, clientDetector, proxyFetch (patches global fetch), cursorProtobuf/cursorChecksum, ollamaTransform.

Conventions

• Config-driven, DRY, camelCase. NEVER hardcode values, models, or block/role strings — use config/ + schema/ constants.
• Translator pipeline pivots through OpenAI as the intermediate format. A translator registered on the exact source:target pair (e.g. claude:kiro) runs as a direct route, skipping the lossy double-hop.
• Translators self-register via register(from, to, reqFn, resFn) as an import side-effect — new files MUST be imported in translator/index.js.

How to add

• Provider: copy providers/REGISTRY_TEMPLATE.js → providers/registry/{id}.js; add models to config/providerModels.js. Generic providers need no executor (DefaultExecutor handles OpenAI-compatible APIs).
• Executor (only for non-standard upstream): subclass BaseExecutor (override getBaseUrls/buildHeaders/buildUrl/execute), register in executors/index.js map. getExecutor falls back to DefaultExecutor when absent.
• Translator: add request|response/<from>-to-<to>.js calling register(...), then import it in translator/index.js. Reuse schema/ + concerns/ — don't re-implement parsing.

Pricing model

providers/pricing.js is the static layer; src/lib/db/repos/pricingRepo.js is the async overlay. Sovereignty order for any lookup: user overrides (kv scope pricing) → synced rates (scope pricing_sync) → the seven-stratum static chain: UNPRICEABLE manifest → PROVIDER_PRICING lane (registry id, then alias) → MODEL_PRICING exact → FREE_ALIAS_MAP inheritance (exact strata only, never globs; FREE_DENYLIST blocks suffix-strip on infix/router traps) → vendor-stripped exact → pre-compiled PATTERN_PRICING.

• Rates are five fields, $/1M tokens: input, output, cached, reasoning, cache_creation. Never add a sixth — fallbacks live in the cost math.
• Usage cost is computed at WRITE time and frozen in the usage DB — no backfill, no recomputation after rate edits.
• matchPattern globs are ANCHORED (^…$) and case-insensitive — consumed by capabilities.js + thinkingLevels.js; preserve semantics when touching PATTERN_PRICING.
• Sync refresh: POST /api/pricing/sync fetches ONLY the hardcoded URLs in SYNC_VENDOR_MAP (SSRF defense — body selects vendors by key, never URLs), writes scope pricing_sync atomically, never touches user overrides. Dashboard shore: /dashboard/settings/pricing.
• Free models inherit their paid sibling's rates everywhere (R3): register siblings in FREE_ALIAS_MAP (hand-verified), never invent entries whose sibling doesn't resolve — the census test suite pins this.
• Rate-table changes: re-run node tests/__baseline__/snapshot-pricing-census.mjs; verify-pricing-census.mjs fails on silent shrinkage.

Pitfalls

• OpenAI bridge is lossy (thinking, non-base64 images, tool ids, is_error) — prefer a direct route for fragile pairs.
• registry/index.js is an auto-generated static import list; regenerate it (don't hand-edit) after adding a registry/{id}.js. REGISTRY_TEMPLATE is excluded by design.
• Special binary/protobuf formats (kiro EventStream, cursor protobuf, commandcode NDJSON) don't round-trip through OpenAI — handle in their executor.
• rtk/ + headroom.js mutate the request body in-place and are fail-open: any error returns null and leaves the body untouched — never throw out of them. RTK skips is_error/status:"error" tool results to preserve traces.