Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript

feat(llm): add Novita provider via a Responses-API translation adapter (#55)

jax-novitabd8dba8e45c9
diff --git a/server/src/__tests__/novita.test.ts b/server/src/__tests__/novita.test.ts
new file mode 100644
index 0000000..7f6a87a
--- /dev/null
+++ b/server/src/__tests__/novita.test.ts
@@ -0,0 +1,223 @@
+/**
+ * Unit tests for the Novita Chat-Completions ↔ Responses-API translation
+ * adapter (server/src/novita.ts). No network access: `chat.completions.create`
+ * is stubbed via `__setNovitaClientOverrideForTesting` so these tests assert
+ * only the translation logic, not live Novita behavior (that's QA's job with
+ * a real NOVITA_API_KEY).
+ *
+ * Run: node --import tsx --test server/src/__tests__/novita.test.ts
+ */
+
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import type OpenAI from 'openai'
+import type { ChatCompletionChunk } from 'openai/resources/chat/completions'
+import type { ResponseInputItem, ResponseStreamEvent } from 'openai/resources/responses/responses'
+import { applyResponseStreamEvent, consumeResponseStream, newResponseStreamState } from '../agents/turn-stream.js'
+import {
+ __setNovitaClientOverrideForTesting,
+ isNovitaModel,
+ novitaResponsesShim,
+ stripNovitaPrefix,
+} from '../novita.js'
+
+function fakeClient(create: (...args: unknown[]) => unknown): OpenAI {
+ return { chat: { completions: { create } } } as unknown as OpenAI
+}
+
+async function* asAsync<T>(items: T[]): AsyncGenerator<T> {
+ for (const item of items) yield item
+}
+
+test('isNovitaModel / stripNovitaPrefix', () => {
+ assert.equal(isNovitaModel('novita/deepseek/deepseek-v3.2'), true)
+ assert.equal(isNovitaModel('gpt-5.5'), false)
+ assert.equal(isNovitaModel(null), false)
+ assert.equal(isNovitaModel(undefined), false)
+ assert.equal(stripNovitaPrefix('novita/deepseek/deepseek-v3.2'), 'deepseek/deepseek-v3.2')
+})
+
+test('non-streaming: translates instructions+input to system+user messages, tools to nested function shape, drops tool_choice/reasoning', async () => {
+ let capturedBody: Record<string, unknown> = {}
+ __setNovitaClientOverrideForTesting(fakeClient(async (args: unknown) => {
+ const body = args as Record<string, unknown>
+ capturedBody = body
+ return {
+ id: 'chatcmpl-1',
+ choices: [{ message: { role: 'assistant', content: 'hello there', tool_calls: [] } }],
+ usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+ }
+ }))
+ try {
+ const r = await novitaResponsesShim.create({
+ model: 'novita/deepseek/deepseek-v3.2',
+ instructions: 'be terse',
+ input: 'hi',
+ tools: [{ type: 'function', name: 'bash', parameters: { type: 'object' }, strict: true, description: 'run a shell command' }],
+ tool_choice: 'auto',
+ reasoning: { effort: 'low' },
+ max_output_tokens: 500,
+ } as never) as { output_text: string; usage: unknown }
+ assert.equal(r.output_text, 'hello there')
+ assert.deepEqual(r.usage, {
+ input_tokens: 10,
+ input_tokens_details: { cached_tokens: 0 },
+ output_tokens: 5,
+ output_tokens_details: { reasoning_tokens: 0 },
+ total_tokens: 15,
+ })
+ // Model prefix stripped before hitting Novita.
+ assert.equal(capturedBody.model, 'deepseek/deepseek-v3.2')
+ assert.deepEqual(capturedBody.messages, [
+ { role: 'system', content: 'be terse' },
+ { role: 'user', content: 'hi' },
+ ])
+ assert.deepEqual(capturedBody.tools, [
+ { type: 'function', function: { name: 'bash', description: 'run a shell command', parameters: { type: 'object' } } },
+ ])
+ assert.equal(capturedBody.max_tokens, 500)
+ // Explicitly NOT forwarded — undocumented on Novita's Chat Completions.
+ assert.equal('tool_choice' in capturedBody, false)
+ assert.equal('reasoning' in capturedBody, false)
+ } finally {
+ __setNovitaClientOverrideForTesting(null)
+ }
+})
+
+test('non-streaming: a tool-call response maps to Responses-shaped function_call output items', async () => {
+ __setNovitaClientOverrideForTesting(fakeClient(async () => ({
+ id: 'chatcmpl-2',
+ choices: [{
+ message: {
+ role: 'assistant',
+ content: null,
+ tool_calls: [{ id: 'call_abc', type: 'function', function: { name: 'bash', arguments: '{"cmd":"ls"}' } }],
+ },
+ }],
+ usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+ })))
+ try {
+ const r = await novitaResponsesShim.create({
+ model: 'novita/glm/glm-4.6',
+ input: [{ role: 'user', content: 'list files' } as unknown as ResponseInputItem],
+ } as never) as { output: Array<{ type: string; call_id: string; name: string; arguments: string }> }
+ assert.equal(r.output.length, 1)
+ assert.equal(r.output[0].type, 'function_call')
+ assert.equal(r.output[0].call_id, 'call_abc')
+ assert.equal(r.output[0].name, 'bash')
+ assert.equal(r.output[0].arguments, '{"cmd":"ls"}')
+ } finally {
+ __setNovitaClientOverrideForTesting(null)
+ }
+})
+
+test('input translation: consecutive function_call items bundle into ONE assistant message with tool_calls; function_call_output becomes role=tool', async () => {
+ let capturedMessages: unknown[] = []
+ __setNovitaClientOverrideForTesting(fakeClient(async (args: unknown) => {
+ const body = args as Record<string, unknown>
+ capturedMessages = body.messages as unknown[]
+ return { id: 'x', choices: [{ message: { role: 'assistant', content: 'ok', tool_calls: [] } }], usage: null }
+ }))
+ try {
+ await novitaResponsesShim.create({
+ model: 'novita/foo/bar',
+ input: [
+ { role: 'user', content: [{ type: 'input_text', text: 'do two things' }] } as unknown as ResponseInputItem,
+ { type: 'function_call', call_id: 'call_1', name: 'bash', arguments: '{"cmd":"a"}' } as unknown as ResponseInputItem,
+ { type: 'function_call', call_id: 'call_2', name: 'bash', arguments: '{"cmd":"b"}' } as unknown as ResponseInputItem,
+ { type: 'function_call_output', call_id: 'call_1', output: 'out-a' } as unknown as ResponseInputItem,
+ { type: 'function_call_output', call_id: 'call_2', output: 'out-b' } as unknown as ResponseInputItem,
+ ],
+ } as never)
+ assert.equal(capturedMessages.length, 4)
+ assert.deepEqual(capturedMessages[0], { role: 'user', content: [{ type: 'text', text: 'do two things' }] })
+ const assistantMsg = capturedMessages[1] as { role: string; tool_calls: Array<{ id: string; function: { name: string; arguments: string } }> }
+ assert.equal(assistantMsg.role, 'assistant')
+ assert.equal(assistantMsg.tool_calls.length, 2)
+ assert.equal(assistantMsg.tool_calls[0].id, 'call_1')
+ assert.equal(assistantMsg.tool_calls[0].function.arguments, '{"cmd":"a"}')
+ assert.equal(assistantMsg.tool_calls[1].id, 'call_2')
+ assert.deepEqual(capturedMessages[2], { role: 'tool', tool_call_id: 'call_1', content: 'out-a' })
+ assert.deepEqual(capturedMessages[3], { role: 'tool', tool_call_id: 'call_2', content: 'out-b' })
+ } finally {
+ __setNovitaClientOverrideForTesting(null)
+ }
+})
+
+test('streaming: text-only reply produces created → output_text.delta* → completed, consumable by the real turn-stream reducer', async () => {
+ const chunks: ChatCompletionChunk[] = [
+ { id: 'c1', created: 0, model: 'x', object: 'chat.completion.chunk', choices: [{ index: 0, delta: { content: 'Hel' }, finish_reason: null }] } as unknown as ChatCompletionChunk,
+ { id: 'c1', created: 0, model: 'x', object: 'chat.completion.chunk', choices: [{ index: 0, delta: { content: 'lo' }, finish_reason: null }] } as unknown as ChatCompletionChunk,
+ { id: 'c1', created: 0, model: 'x', object: 'chat.completion.chunk', choices: [{ index: 0, delta: {}, finish_reason: 'stop' }], usage: { prompt_tokens: 3, completion_tokens: 2, total_tokens: 5 } } as unknown as ChatCompletionChunk,
+ ]
+ __setNovitaClientOverrideForTesting(fakeClient(async () => asAsync(chunks)))
+ try {
+ const stream = await novitaResponsesShim.create({
+ model: 'novita/deepseek/deepseek-v3.2',
+ input: 'hi',
+ stream: true,
+ } as never) as AsyncIterable<ResponseStreamEvent>
+
+ const events: ResponseStreamEvent[] = []
+ for await (const ev of stream) events.push(ev)
+ assert.equal(events[0].type, 'response.created')
+ assert.equal(events.filter((e) => e.type === 'response.output_text.delta').length, 2)
+ const last = events[events.length - 1]
+ assert.equal(last.type, 'response.completed')
+
+ // Feed straight through the PRODUCTION reducer — proves turn.ts's real
+ // consumption path (no code changes there) understands these events.
+ const state = newResponseStreamState()
+ for (const ev of events) applyResponseStreamEvent(state, ev)
+ assert.equal(Array.from(state.responseTextByPart.values()).join(''), 'Hello')
+ assert.equal(state.responseStatus, 'completed')
+ assert.equal(state.totalTokens, 5)
+ assert.deepEqual(state.pendingTools, {})
+ } finally {
+ __setNovitaClientOverrideForTesting(null)
+ }
+})
+
+test('streaming: tool-call reply produces output_item.added + function_call_arguments.delta/done, reducible to pendingTools', async () => {
+ const chunks: ChatCompletionChunk[] = [
+ {
+ id: 'c1', created: 0, model: 'x', object: 'chat.completion.chunk',
+ choices: [{ index: 0, delta: { tool_calls: [{ index: 0, id: 'call_xyz', function: { name: 'bash', arguments: '' } }] }, finish_reason: null }],
+ } as unknown as ChatCompletionChunk,
+ {
+ id: 'c1', created: 0, model: 'x', object: 'chat.completion.chunk',
+ choices: [{ index: 0, delta: { tool_calls: [{ index: 0, function: { arguments: '{"cmd":' } }] }, finish_reason: null }],
+ } as unknown as ChatCompletionChunk,
+ {
+ id: 'c1', created: 0, model: 'x', object: 'chat.completion.chunk',
+ choices: [{ index: 0, delta: { tool_calls: [{ index: 0, function: { arguments: '"ls"}' } }] }, finish_reason: null }],
+ } as unknown as ChatCompletionChunk,
+ {
+ id: 'c1', created: 0, model: 'x', object: 'chat.completion.chunk',
+ choices: [{ index: 0, delta: {}, finish_reason: 'tool_calls' }],
+ usage: { prompt_tokens: 4, completion_tokens: 6, total_tokens: 10 },
+ } as unknown as ChatCompletionChunk,
+ ]
+ __setNovitaClientOverrideForTesting(fakeClient(async () => asAsync(chunks)))
+ try {
+ const stream = await novitaResponsesShim.create({
+ model: 'novita/qwen/qwen3-max',
+ input: 'list files',
+ tools: [{ type: 'function', name: 'bash', parameters: {}, strict: true }],
+ stream: true,
+ } as never) as AsyncIterable<ResponseStreamEvent>
+
+ const state = newResponseStreamState()
+ await consumeResponseStream(stream, (ev) => applyResponseStreamEvent(state, ev))
+
+ const tools = Object.values(state.pendingTools)
+ assert.equal(tools.length, 1)
+ assert.equal(tools[0].call_id, 'call_xyz')
+ assert.equal(tools[0].name, 'bash')
+ assert.equal(tools[0].arguments, '{"cmd":"ls"}')
+ assert.equal(state.responseStatus, 'completed')
+ assert.equal(state.totalTokens, 10)
+ } finally {
+ __setNovitaClientOverrideForTesting(null)
+ }
+})
diff --git a/server/src/env.ts b/server/src/env.ts
index ded1951..8f0686b 100644
--- a/server/src/env.ts
+++ b/server/src/env.ts
@@ -58,6 +58,16 @@ export const env = {
* (e.g. nano) for these calls specifically.
*/
OPENAI_COMPACTION_MODEL: process.env.OPENAI_COMPACTION_MODEL ?? DEFAULT_SUPPORT_MODEL,
+ /**
+ * Novita LLM API key. Optional — when unset, agents configured with a
+ * `novita/<model>` model id (see server/src/novita.ts) fall back to the
+ * legacy/sub2api client instead, so an unconfigured deployment doesn't
+ * break the run; the model just won't resolve to Novita as intended.
+ */
+ NOVITA_API_KEY: process.env.NOVITA_API_KEY ?? '',
+ /** Novita's OpenAI-compatible Chat Completions base. Override for a
+ * self-hosted proxy or a pinned API version. */
+ NOVITA_BASE_URL: (process.env.NOVITA_BASE_URL ?? 'https://api.novita.ai/openai').replace(/\/+$/, ''),
/**
* Webhook URL for process-level alerts (unhandledRejection /
* uncaughtException). Currently expects a Discord-compatible
diff --git a/server/src/llm.ts b/server/src/llm.ts
index 61fc1db..b6052a5 100644
--- a/server/src/llm.ts
+++ b/server/src/llm.ts
@@ -22,10 +22,21 @@
* Critical: failures resolving the sub2api key are NEVER fatal — we
* fall back to the legacy client. A wedged sub2api lookup must not
* take down agent turns.
+ *
+ * Provider routing (model-based, on top of the above): whichever client is
+ * chosen by the tenant rules is wrapped by `withNovitaRouting` before it's
+ * returned. That wrapper inspects the `model` on each individual
+ * `responses.create()` call — not the tenant — and reroutes calls whose
+ * model carries the `novita/` prefix to Novita's real Chat Completions API
+ * via server/src/novita.ts's translation shim, since Novita has no Responses
+ * API to swap a base URL onto. Everything else about the returned client
+ * (chat.completions, images, embeddings, non-Novita responses.create calls)
+ * is the same object callers already know.
*/
import OpenAI from 'openai'
import { pool } from './db/pool.js'
import { env } from './env.js'
+import { isNovitaModel, novitaResponsesShim } from './novita.js'
import { sub2apiConfigured, sub2apiOpenAIBaseURL } from './sub2api.js'
interface CachedClient {
@@ -64,17 +75,67 @@ export function __setLlmClientOverrideForTesting(fn: typeof testLlmOverride): vo
testLlmOverride = fn
}
+/** Wrap a client so any call whose `model` carries the `novita/` prefix
+ * (see server/src/novita.ts) is routed to Novita's real Chat Completions
+ * API instead of this client's own `responses.create` — translated
+ * through `novitaResponsesShim` so the caller sees an ordinary
+ * Responses-API stream/return either way.
+ *
+ * Model, not tenant, decides the provider: `getLlmClient` is resolved
+ * once per tenant/hop before the model for that specific call is even
+ * read off `args.model`, so routing has to happen at `.responses.create()`
+ * call time, not here. Every caller in this codebase reads only
+ * `client.responses.create(...)`, so wrapping just that property is a
+ * complete, minimal interception — everything else (chat.completions,
+ * images, embeddings) passes through to the real client untouched. */
+let novitaUnconfiguredWarned = false
+/** One log line, not one per call — this fires on every hop of every turn of
+ * an agent whose model names an unconfigured provider. */
+function warnNovitaUnconfiguredOnce(model: string | undefined): void {
+ if (novitaUnconfiguredWarned) return
+ novitaUnconfiguredWarned = true
+ console.warn(`[llm] model "${model}" requests Novita but NOVITA_API_KEY is unset — using the tenant's normal client instead`)
+}
+
+function withNovitaRouting(client: OpenAI): OpenAI {
+ return new Proxy(client, {
+ get(target, prop, receiver): unknown {
+ if (prop !== 'responses') return Reflect.get(target, prop, receiver)
+ const real = target.responses
+ return new Proxy(real, {
+ get(rt, p, rr): unknown {
+ if (p !== 'create') return Reflect.get(rt, p, rr)
+ return (args: { model?: string } & Record<string, unknown>, opts?: unknown) => {
+ if (isNovitaModel(args.model)) {
+ // Route to Novita only when this deployment actually configured
+ // a key — otherwise fall through to the tenant's normal client,
+ // exactly as env.ts documents. Without this guard an unset key
+ // sent the call to api.novita.ai with an empty bearer and the
+ // agent died on an unexplained 401 instead of degrading.
+ if (env.NOVITA_API_KEY) {
+ return novitaResponsesShim.create(args as never, opts as never)
+ }
+ warnNovitaUnconfiguredOnce(args.model)
+ }
+ return (real.create as (a: unknown, o?: unknown) => unknown)(args, opts)
+ }
+ },
+ })
+ },
+ })
+}
+
/** Build (and cache) the OpenAI client for this tenant. Async because
* resolving the tenant's owner_user_id + sub2api_api_key is a DB hop.
* Always returns a working client — never throws on lookup failure. */
export async function getLlmClient(tenant: string | null): Promise<OpenAI> {
if (testLlmOverride) return testLlmOverride(tenant)
// No tenant context → legacy.
- if (!tenant || !sub2apiConfigured()) return legacyClient()
+ if (!tenant || !sub2apiConfigured()) return withNovitaRouting(legacyClient())
const cached = cache.get(tenant)
if (cached && Date.now() - cached.mintedAt < CACHE_TTL_MS) {
- return cached.client
+ return withNovitaRouting(cached.client)
}
try {
@@ -92,7 +153,7 @@ export async function getLlmClient(tenant: string | null): Promise<OpenAI> {
// hop, but with a short TTL so the next backfill picks up quickly.
const c = legacyClient()
cache.set(tenant, { client: c, key: 'legacy', mintedAt: Date.now() })
- return c
+ return withNovitaRouting(c)
}
const c = new OpenAI({
apiKey,
@@ -101,10 +162,10 @@ export async function getLlmClient(tenant: string | null): Promise<OpenAI> {
timeout: SDK_TIMEOUT_MS,
})
cache.set(tenant, { client: c, key: apiKey, mintedAt: Date.now() })
- return c
+ return withNovitaRouting(c)
} catch (e) {
console.warn(`[llm] tenant ${tenant} client lookup failed; legacy fallback`, e instanceof Error ? e.message : e)
- return legacyClient()
+ return withNovitaRouting(legacyClient())
}
}
diff --git a/server/src/novita.ts b/server/src/novita.ts
new file mode 100644
index 0000000..9388118
--- /dev/null
+++ b/server/src/novita.ts
@@ -0,0 +1,449 @@
+/**
+ * Novita LLM API provider — translation adapter, NOT a base-URL swap.
+ *
+ * Novita's public LLM surface is OpenAI-compatible ONLY at the Chat
+ * Completions layer (`POST /openai/v1/chat/completions`). It has no
+ * Responses API (`/v1/responses`) equivalent. Every call site in this
+ * codebase (turn.ts's streaming hops, convene.ts, agenda.ts, inbox-triage.ts,
+ * ...) is written against `client.responses.create(...)` — Responses-shaped
+ * request params, Responses-shaped streaming events (`response.created`,
+ * `response.output_text.delta`, `response.function_call_arguments.delta/done`,
+ * `response.completed`), and `Response.output_text` / `.output` on the
+ * synchronous return. Pointing an `OpenAI` SDK client's `baseURL` at Novita
+ * would NOT make any of that work — the SDK would call `POST /responses`
+ * against a host that doesn't implement it.
+ *
+ * This module bridges the gap: it accepts Responses-API-shaped request
+ * params, translates them into Chat Completions params, calls Novita's real
+ * `chat.completions.create`, and translates the result (streaming or not)
+ * back into the exact Responses-API shapes every existing call site already
+ * expects. Nothing outside `llm.ts` needs to change — see `withNovitaRouting`
+ * there for how a per-call `model` id opts into this path.
+ *
+ * Model selection convention: an agent (or an env default) opts into Novita
+ * by prefixing its `model` with `novita/`, e.g. `novita/deepseek/deepseek-v3.2`.
+ * The prefix is stripped before the model id is sent to Novita.
+ */
+import OpenAI from 'openai'
+import type {
+ ChatCompletionChunk,
+ ChatCompletionFunctionTool,
+ ChatCompletionMessageFunctionToolCall,
+ ChatCompletionMessageParam,
+ ChatCompletionToolMessageParam,
+} from 'openai/resources/chat/completions'
+import type {
+ FunctionTool,
+ ResponseInputItem,
+ ResponseStreamEvent,
+} from 'openai/resources/responses/responses'
+import { env } from './env.js'
+
+export const NOVITA_MODEL_PREFIX = 'novita/'
+
+export function isNovitaModel(model: string | null | undefined): boolean {
+ return typeof model === 'string' && model.startsWith(NOVITA_MODEL_PREFIX)
+}
+
+export function stripNovitaPrefix(model: string): string {
+ return model.slice(NOVITA_MODEL_PREFIX.length)
+}
+
+let _novitaClient: OpenAI | null = null
+/** Test-only override for the underlying Novita client — lets unit tests
+ * exercise the translation logic (toChatMessages / streaming / usage
+ * mapping) against a fake `chat.completions.create` without a real
+ * NOVITA_API_KEY or network access. Production code never sets this. */
+let testNovitaClientOverride: OpenAI | null = null
+export function __setNovitaClientOverrideForTesting(client: OpenAI | null): void {
+ testNovitaClientOverride = client
+}
+function novitaClient(): OpenAI {
+ if (testNovitaClientOverride) return testNovitaClientOverride
+ if (!_novitaClient) {
+ _novitaClient = new OpenAI({
+ apiKey: env.NOVITA_API_KEY,
+ baseURL: env.NOVITA_BASE_URL,
+ })
+ }
+ return _novitaClient
+}
+
+/** Loose shape covering every field the existing call sites actually pass
+ * to `client.responses.create(...)`. We don't import the SDK's own params
+ * types here because several call sites (e.g. `verifyTerminalCompletion`)
+ * smuggle `signal` into the body via an `as unknown as` cast, which the
+ * real SDK types don't model — so a loose shape is the honest contract. */
+interface ResponsesCreateArgs {
+ model: string
+ instructions?: string | null
+ input?: string | ResponseInputItem[]
+ tools?: FunctionTool[]
+ tool_choice?: unknown
+ reasoning?: { effort?: string | null } | null
+ max_output_tokens?: number | null
+ stream?: boolean
+ text?: { format?: { type?: string } }
+ signal?: AbortSignal | null
+}
+
+interface RequestOpts {
+ signal?: AbortSignal | null
+ maxRetries?: number
+ timeout?: number
+ [key: string]: unknown
+}
+
+/** Build the per-call request options object passed to the underlying SDK's
+ * `chat.completions.create(body, options)`. Every failed live smoke against
+ * this shim (QA's `APIConnectionTimeoutError`) traced back to this line:
+ * the SDK's `buildRequest` guards `timeout` with `if ('timeout' in options)`
+ * — not a nullish check — so `{ timeout: opts?.timeout }` with `opts`
+ * omitted still puts a `timeout: undefined` KEY on the object, which trips
+ * `validatePositiveInteger('timeout', undefined)` and throws `OpenAIError:
+ * timeout must be an integer` before any request is ever sent. That thrown
+ * error then classifies as a connection failure upstream in turn.ts, which
+ * is why it surfaced as a timeout instead of a type error. Only set a key
+ * when its value is actually present. */
+function toRequestOptions(args: ResponsesCreateArgs, opts?: RequestOpts): RequestOpts {
+ const options: RequestOpts = {}
+ const signal = opts?.signal ?? args.signal
+ if (signal != null) options.signal = signal
+ if (opts?.maxRetries != null) options.maxRetries = opts.maxRetries
+ if (opts?.timeout != null) options.timeout = opts.timeout
+ return options
+}
+
+function toChatTools(tools: FunctionTool[] | undefined): ChatCompletionFunctionTool[] | undefined {
+ if (!tools || tools.length === 0) return undefined
+ return tools.map((t) => ({
+ type: 'function',
+ function: {
+ name: t.name,
+ description: t.description ?? undefined,
+ parameters: t.parameters ?? undefined,
+ },
+ }))
+}
+
+/** Translate Responses-API `input` items into Chat Completions messages.
+ *
+ * The two API shapes disagree on where a tool call lives: Responses spreads
+ * the assistant's text and each function call across separate flat items;
+ * Chat Completions bundles every tool call from one turn into the SAME
+ * assistant message's `tool_calls` array, with `role:'tool'` messages
+ * following for each output. `turn.ts` always pushes a hop's function_call
+ * items back-to-back, then its function_call_output items back-to-back
+ * (`history.push(...assistantOutputItems, ...outs)`), so buffering
+ * consecutive function_call items into one assistant message and flushing
+ * on the next non-function_call item reconstructs the Chat Completions
+ * shape losslessly for every input this codebase actually produces. */
+function toChatMessages(
+ instructions: string | null | undefined,
+ input: string | ResponseInputItem[] | undefined,
+): ChatCompletionMessageParam[] {
+ const messages: ChatCompletionMessageParam[] = []
+ if (instructions) messages.push({ role: 'system', content: instructions })
+ if (typeof input === 'string') {
+ if (input) messages.push({ role: 'user', content: input })
+ return messages
+ }
+ if (!input) return messages
+
+ let pendingCalls: Array<{ id: string; name: string; arguments: string }> = []
+ const flushPendingCalls = (): void => {
+ if (pendingCalls.length === 0) return
+ messages.push({
+ role: 'assistant',
+ content: null,
+ tool_calls: pendingCalls.map((c) => ({
+ id: c.id,
+ type: 'function',
+ function: { name: c.name, arguments: c.arguments },
+ })),
+ })
+ pendingCalls = []
+ }
+
+ for (const raw of input) {
+ const item = raw as unknown as Record<string, unknown>
+ const type = String(item.type ?? 'message')
+ if (type === 'function_call') {
+ pendingCalls.push({
+ id: String(item.call_id ?? item.id ?? ''),
+ name: String(item.name ?? ''),
+ arguments: String(item.arguments ?? ''),
+ })
+ continue
+ }
+ flushPendingCalls()
+ if (type === 'function_call_output') {
+ const output = item.output
+ messages.push({
+ role: 'tool',
+ tool_call_id: String(item.call_id ?? ''),
+ content: typeof output === 'string' ? output : JSON.stringify(output ?? ''),
+ } as ChatCompletionToolMessageParam)
+ continue
+ }
+ // A message item: role + string or content-part-array content.
+ const role = String(item.role ?? 'user')
+ const chatRole = role === 'assistant' ? 'assistant' : role === 'system' || role === 'developer' ? 'system' : 'user'
+ const content = item.content
+ if (typeof content === 'string') {
+ messages.push({ role: chatRole, content } as ChatCompletionMessageParam)
+ continue
+ }
+ if (Array.isArray(content)) {
+ const parts = content
+ .map((c) => c as Record<string, unknown>)
+ .map((c) => {
+ const cType = String(c.type ?? '')
+ if (cType === 'input_image') {
+ return {
+ type: 'image_url' as const,
+ image_url: { url: String(c.image_url ?? ''), detail: (c.detail as 'auto' | 'low' | 'high' | undefined) ?? 'auto' },
+ }
+ }
+ // input_text / output_text / anything else text-shaped.
+ return { type: 'text' as const, text: String(c.text ?? '') }
+ })
+ messages.push({ role: chatRole, content: parts } as ChatCompletionMessageParam)
+ continue
+ }
+ }
+ flushPendingCalls()
+ return messages
+}
+
+/** Chat Completions `usage` (prompt_tokens/completion_tokens) → the Responses
+ * API's `ResponseUsage` shape (input_tokens/output_tokens), so downstream
+ * readers (`usageFromOpenAI`, `readStreamReasoningTokens`, `turn-stream.ts`)
+ * work unchanged. */
+function toResponseUsage(raw: unknown): Record<string, unknown> | null {
+ const u = raw as {
+ prompt_tokens?: number
+ completion_tokens?: number
+ total_tokens?: number
+ prompt_tokens_details?: { cached_tokens?: number }
+ completion_tokens_details?: { reasoning_tokens?: number }
+ } | null | undefined
+ if (!u) return null
+ return {
+ input_tokens: u.prompt_tokens ?? 0,
+ input_tokens_details: { cached_tokens: u.prompt_tokens_details?.cached_tokens ?? 0 },
+ output_tokens: u.completion_tokens ?? 0,
+ output_tokens_details: { reasoning_tokens: u.completion_tokens_details?.reasoning_tokens ?? 0 },
+ total_tokens: u.total_tokens ?? 0,
+ }
+}
+
+/** Build the Chat Completions request body from Responses-API args.
+ *
+ * Known gap, called out explicitly per the task ask ("don't assume base-URL
+ * swap = compatible"): Novita's documented Chat Completions params do not
+ * include `tool_choice` — only `tools` ("currently, only functions are
+ * supported as a tool"). Chat Completions itself defaults `tool_choice` to
+ * `'auto'` whenever `tools` is non-empty, matching the ONLY value every
+ * call site in this repo ever passes (`tool_choice: 'auto'`), so we
+ * deliberately drop the field rather than forward a param Novita doesn't
+ * document — sending an unsupported field risks a hard 4xx instead of a
+ * silent default. `reasoning.effort` has no Chat Completions equivalent
+ * either (Novita's reasoning knobs — `separate_reasoning`, `enable_thinking`
+ * — are model-specific and orthogonal); we drop it rather than guess. */
+function buildChatBody(args: ResponsesCreateArgs, stream: boolean): Record<string, unknown> {
+ const body: Record<string, unknown> = {
+ model: stripNovitaPrefix(args.model),
+ messages: toChatMessages(args.instructions, args.input),
+ stream,
+ }
+ const tools = toChatTools(args.tools)
+ if (tools) body.tools = tools
+ if (args.max_output_tokens != null) body.max_tokens = args.max_output_tokens
+ if (args.text?.format?.type === 'json_object') body.response_format = { type: 'json_object' }
+ if (stream) body.stream_options = { include_usage: true }
+ return body
+}
+
+/** Non-streaming call. Every non-streaming Responses-shaped call site reads
+ * `r.output_text` (and nothing else off the return besides `.usage` via
+ * `getTrackedLlmClient`'s wrapper) — so translating just that + `.usage`
+ * covers convene.ts / agenda.ts / inbox-triage.ts / router.ts / etc. in
+ * full. */
+async function createNonStreaming(args: ResponsesCreateArgs, opts?: RequestOpts): Promise<Record<string, unknown>> {
+ const body = buildChatBody(args, false)
+ const completion = await novitaClient().chat.completions.create(
+ body as unknown as Parameters<OpenAI['chat']['completions']['create']>[0] & { stream?: false },
+ toRequestOptions(args, opts),
+ )
+ const choice = completion.choices[0]
+ const outputText = choice?.message?.content ?? ''
+ const toolCalls = (choice?.message?.tool_calls ?? []).filter(
+ (tc): tc is ChatCompletionMessageFunctionToolCall => tc.type === 'function',
+ )
+ const output = toolCalls.length > 0
+ ? toolCalls.map((tc) => ({
+ type: 'function_call' as const,
+ call_id: tc.id,
+ name: tc.function.name,
+ arguments: tc.function.arguments,
+ }))
+ : outputText
+ ? [{ type: 'message' as const, role: 'assistant' as const, content: [{ type: 'output_text' as const, text: outputText }] }]
+ : []
+ return {
+ id: completion.id,
+ output_text: outputText,
+ output,
+ usage: toResponseUsage(completion.usage),
+ status: 'completed',
+ }
+}
+
+/** Streaming call — translates `ChatCompletionChunk`s into the exact
+ * `ResponseStreamEvent` sequence `turn-stream.ts`'s reducer expects:
+ * `response.created` → `response.output_text.delta`* →
+ * `response.output_item.added` + `response.function_call_arguments.delta`*
+ * (one per tool call) → `response.completed`. This is the ONLY event
+ * sequence turn.ts's hop loop and `applyResponseStreamEvent` consume; every
+ * other Responses event type is unused by this codebase (confirmed by
+ * reading turn-stream.ts's reducer), so it's the full translation surface
+ * needed, not a partial shim. */
+async function* createStreaming(
+ args: ResponsesCreateArgs,
+ opts?: RequestOpts,
+): AsyncGenerator<ResponseStreamEvent> {
+ const body = buildChatBody(args, true)
+ const stream = await novitaClient().chat.completions.create(
+ body as unknown as Parameters<OpenAI['chat']['completions']['create']>[0] & { stream: true },
+ toRequestOptions(args, opts),
+ )
+
+ const responseId = `novita-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+ yield {
+ type: 'response.created',
+ sequence_number: 0,
+ response: { id: responseId, status: 'in_progress' },
+ } as unknown as ResponseStreamEvent
+
+ const itemId = `${responseId}-msg`
+ let textEmitted = false
+ // Keyed by tool_call index — Chat Completions streams tool-call argument
+ // deltas by array index, not a stable id (the id itself may only appear
+ // on the first delta for that index).
+ const toolCallsByIndex = new Map<number, { id: string; name: string; arguments: string }>()
+ let usage: unknown = null
+ let seq = 1
+
+ for await (const chunk of stream as AsyncIterable<ChatCompletionChunk>) {
+ if (chunk.usage) usage = chunk.usage
+ const delta = chunk.choices?.[0]?.delta
+ if (!delta) continue
+ if (delta.content) {
+ textEmitted = true
+ yield {
+ type: 'response.output_text.delta',
+ item_id: itemId,
+ content_index: 0,
+ delta: delta.content,
+ sequence_number: seq++,
+ } as unknown as ResponseStreamEvent
+ }
+ for (const tc of delta.tool_calls ?? []) {
+ const idx = tc.index
+ let entry = toolCallsByIndex.get(idx)
+ if (!entry) {
+ entry = { id: tc.id ?? `call_${idx}`, name: tc.function?.name ?? '', arguments: '' }
+ toolCallsByIndex.set(idx, entry)
+ yield {
+ type: 'response.output_item.added',
+ output_index: idx,
+ sequence_number: seq++,
+ item: {
+ type: 'function_call',
+ id: `${responseId}-fc-${idx}`,
+ call_id: entry.id,
+ name: entry.name,
+ arguments: '',
+ },
+ } as unknown as ResponseStreamEvent
+ }
+ if (tc.function?.arguments) {
+ entry.arguments += tc.function.arguments
+ yield {
+ type: 'response.function_call_arguments.delta',
+ item_id: `${responseId}-fc-${idx}`,
+ output_index: idx,
+ delta: tc.function.arguments,
+ sequence_number: seq++,
+ } as unknown as ResponseStreamEvent
+ }
+ }
+ }
+
+ for (const [idx, entry] of toolCallsByIndex) {
+ yield {
+ type: 'response.function_call_arguments.done',
+ item_id: `${responseId}-fc-${idx}`,
+ output_index: idx,
+ name: entry.name,
+ arguments: entry.arguments,
+ sequence_number: seq++,
+ } as unknown as ResponseStreamEvent
+ }
+
+ const output: unknown[] = []
+ if (textEmitted) {
+ output.push({ type: 'message', id: itemId, role: 'assistant', status: 'completed', content: [] })
+ }
+ for (const [idx, entry] of toolCallsByIndex) {
+ output.push({
+ type: 'function_call',
+ id: `${responseId}-fc-${idx}`,
+ call_id: entry.id,
+ name: entry.name,
+ arguments: entry.arguments,
+ })
+ }
+
+ yield {
+ type: 'response.completed',
+ sequence_number: seq++,
+ response: {
+ id: responseId,
+ status: 'completed',
+ output,
+ usage: toResponseUsage(usage),
+ },
+ } as unknown as ResponseStreamEvent
+}
+
+/** A `Stream<ResponseStreamEvent>`-shaped async iterable. Every consumer in
+ * this codebase only uses `for await` / `consumeResponseStream`'s
+ * `stream[Symbol.asyncIterator]()` — never `Stream`'s other methods
+ * (`.tee()`, `.toReadableStream()`) — so a bare async-iterable object
+ * satisfies every real usage without depending on the SDK's internal
+ * `Stream` class. `controller.abort()` is wired so `turn-stream.ts`'s
+ * idle/wall timeout abort path (`abortStream`) has something to call. */
+function wrapAsyncIterable(gen: AsyncGenerator<ResponseStreamEvent>): AsyncIterable<ResponseStreamEvent> & { controller: AbortController } {
+ const controller = new AbortController()
+ return {
+ controller,
+ [Symbol.asyncIterator]() {
+ return gen
+ },
+ }
+}
+
+/** The Responses-API-shaped surface every call site actually uses off a
+ * client: `client.responses.create(...)`. Assigning this object as
+ * `client.responses` (see `withNovitaRouting` in llm.ts) is sufficient —
+ * nothing in this codebase touches any other `client.responses.*` method. */
+export const novitaResponsesShim = {
+ create(args: ResponsesCreateArgs, opts?: RequestOpts): unknown {
+ if (args.stream) {
+ return Promise.resolve(wrapAsyncIterable(createStreaming(args, opts)))
+ }
+ return createNonStreaming(args, opts)
+ },
+}
diff --git a/src/components/AgentEditor.tsx b/src/components/AgentEditor.tsx
index ed6484c..5246606 100644
--- a/src/components/AgentEditor.tsx
+++ b/src/components/AgentEditor.tsx
@@ -240,7 +240,7 @@ export function AgentEditor({ agent, onClose }: Props) {
label={isByoa ? 'Big-brain model (大脑)' : 'Model'}
hint={isByoa
? `Main reasoning model passed to the engine as --model. ${engine === 'codex' ? 'A model name (e.g. gpt-5.5, o3).' : engine === 'grok' ? 'A Grok model (e.g. grok-4.6).' : engine === 'cursor' ? 'A Cursor model id or alias; blank = Auto.' : "A Claude alias or full name (e.g. opus, sonnet, claude-sonnet-4-6)."} Blank = engine default.`
- : 'Optional — leave blank to use the system default. Any OpenAI model name works (e.g. gpt-5.5, gpt-5.5-pro, gpt-5.5-mini).'}
+ : 'Optional — leave blank to use the system default. Any OpenAI model name works (e.g. gpt-5.5, gpt-5.5-pro, gpt-5.5-mini). Prefix with novita/ to run this agent on Novita instead (e.g. novita/deepseek/deepseek-v3.2).'}
>
<Input
type="text"