cortico 0.1.0

package/src/providers/registry.ts

@@ -0,0 +1,137 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { URL, fileURLToPath, pathToFileURL } from 'node:url';
+import type { LLMProviderEntry } from '../core/types.ts';
+import type { ProviderHostBase, ProviderInstance, ProviderModule } from './base.ts';
+import { quotePrices } from './pricebook.ts';
+import { createHash } from 'node:crypto';
+import { secretReader } from '../core/secrets.ts';
+import type { ResponseClient } from '../core/generation.ts';
+
+/** Modules are discovered from providers/<module>/index.ts. */
+export async function discoverProviderModules(
+  root = fileURLToPath(new URL('.', import.meta.url)),
+): Promise<ProviderModule[]> {
+  const modules: ProviderModule[] = [];
+  for (const dir of readdirSync(root, { withFileTypes: true }).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  )) {
+    if (!dir.isDirectory()) continue;
+    const entry = join(root, dir.name, 'index.ts');
+    if (!existsSync(entry)) continue;
+    const module = (await import(pathToFileURL(entry).href)).default as ProviderModule;
+    if (module.id !== dir.name)
+      throw new Error(`Provider module ID must match directory: ${dir.name}`);
+    modules.push(module);
+  }
+  return modules;
+}
+
+export const providerModules = await discoverProviderModules();
+const byId = new Map(providerModules.map((module) => [module.id, module]));
+
+/**
+ * 追加扩展带来的 provider 模块。就地改这一个数组,不换引用:`ProviderRegistry` 与
+ * `ProviderSettings` 的默认参数引用的就是它,而两者都在启动器注册完之后才构造。
+ * id 撞车直接抛:一个 kind 对应哪份实现不能有歧义。
+ */
+export function registerProviderModules(extra: readonly ProviderModule[]): void {
+  for (const module of extra) {
+    if (byId.has(module.id)) throw new Error(`Provider module id 已被占用: ${module.id}`);
+    byId.set(module.id, module);
+    providerModules.push(module);
+  }
+}
+
+export function providerModule(kind: string): ProviderModule {
+  const module = byId.get(kind);
+  if (!module) throw new Error(`Unknown provider module: ${kind}`);
+  return module;
+}
+
+export class ProviderRegistry {
+  private readonly instances = new Map<string, { key: string; value: ProviderInstance }>();
+  private readonly resources = new Map<string, unknown>();
+  constructor(
+    private readonly entries: () => Record<string, LLMProviderEntry>,
+    private readonly host: ProviderHostBase,
+    private readonly modules: readonly ProviderModule[] = providerModules,
+  ) {}
+
+  private module(kind: string): ProviderModule {
+    const module = this.modules.find((module) => module.id === kind);
+    if (!module) throw new Error(`Unknown provider module: ${kind}`);
+    return module;
+  }
+
+  resolve(name: string): ProviderInstance {
+    const raw = this.entries()[name];
+    if (!raw) throw new Error(`没有这个 LLM provider: ${name}`);
+    const module = this.module(raw.kind);
+    const entry = module.normalize?.(structuredClone(raw)) ?? structuredClone(raw);
+    const { pricing: _pricing, spec: _spec, ...transportEntry } = entry;
+    const key = JSON.stringify(transportEntry);
+    const previous = this.instances.get(name);
+    if (previous?.key === key) return previous.value;
+    // 按端点名分岔的两样在这里填:模块自己的目录,与只读那个目录的密钥链。
+    const { stateRoot, ...base } = this.host;
+    const stateDir = join(stateRoot, name);
+    const value = module.create(name, entry, {
+      ...base,
+      stateDir,
+      secret: secretReader(join(stateDir, '.env')),
+      currentEntry: () =>
+        module.normalize?.(structuredClone(this.entries()[name])) ?? this.entries()[name],
+      resource: <T>(resource: string, create: () => T): T => {
+        const id = JSON.stringify([module.id, name, resource]);
+        if (!this.resources.has(id)) this.resources.set(id, create());
+        return this.resources.get(id) as T;
+      },
+    });
+    this.instances.set(name, { key, value });
+    return value;
+  }
+
+  bind(name: string): ResponseClient {
+    const raw = this.entries()[name];
+    if (!raw) throw new Error(`没有这个 LLM provider: ${name}`);
+    const module = this.module(raw.kind);
+    const entry = module.normalize?.(structuredClone(raw)) ?? structuredClone(raw);
+    const instance = this.resolve(name);
+    const domain = () =>
+      createHash('sha256')
+        .update(JSON.stringify([entry.kind, entry.baseUrl, instance.compatibilityKey?.() ?? null]))
+        .digest('hex');
+    const client: ResponseClient = {
+      bind: () => client,
+      respond: (request, options) =>
+        instance.client.respond(request, {
+          ...options,
+          quote: (at) => quotePrices(entry, request, at, module.prices?.(entry, request, at) ?? []),
+          origin: {
+            instance: name,
+            module: entry.kind,
+            model: request.model ?? '',
+            compatibilityDomain: domain(),
+          },
+        }),
+    };
+    return client;
+  }
+
+  /**
+   * Drop the cached instance so the next resolve rebuilds it; `host.resource` objects
+   * survive. Secrets are read once per instance, so a key written to the endpoint's `.env`
+   * takes effect only through this.
+   */
+  invalidate(name: string): void {
+    this.instances.delete(name);
+  }
+
+  async start(name: string): Promise<unknown> {
+    return this.resolve(name).start?.();
+  }
+  async stopAll(): Promise<void> {
+    await Promise.all([...this.instances.values()].map((instance) => instance.value.stop?.()));
+  }
+}

package/src/providers/strings.ts

@@ -0,0 +1,71 @@
+import { pick, type Language } from '../core/language.ts';
+
+/** Validation errors that reach the console as `{ error }` from the provider settings. */
+const zh = {
+  profileObject: '模型配置必须是对象',
+  modelRequired: '模型名不能为空',
+  thinkingBoolean: '推理开关必须是布尔值',
+  tierUnsupported: (title: string) => `${title} 不支持该推理档位`,
+  effortString: '推理强度必须是非空字符串',
+  effortWithoutThinking: '思维链关闭时不能带推理强度',
+  temperatureRange: 'temperature 必须在 0–2 之间',
+  positiveInteger: (field: string) => `${field} 必须为正整数`,
+  optionsObject: '原生参数必须是对象',
+  kindChange: '实例不能改变 Provider 模块类型',
+  baseUrlFormat: '供应地址需要不含凭据的 HTTP(S) URL',
+  secretName: '密钥引用必须是环境变量名',
+  multimodalBoolean: '多模态开关必须是布尔值',
+  serviceTierString: '服务档必须是字符串',
+  serviceTierUnsupported: (title: string, tier: string) => `${title} 不支持服务档 ${tier}`,
+  pricingArray: '报价必须是数组',
+  rulesArray: '报价规则必须是数组',
+  ruleShape: '报价规则需要计量维度和非负单价',
+  unitRequired: '计量单位不能为空',
+  tokenUnit: '标准 token 计量必须使用 token 单位',
+  bandsArray: '输入阶梯必须是数组',
+  bandsIncreasing: '输入阶梯阈值必须严格递增且大于 0',
+  modelsRequired: '报价需要明确模型名或 *',
+  currencyRequired: '报价币种不能为空',
+  basisValue: '报价口径必须为 marginal 或 equivalent',
+  sourceRequired: '报价需要来源',
+  tiersObject: '服务档报价必须是对象',
+  tierNameRequired: '服务档名不能为空',
+  tierRules: '服务档报价需要规则对象',
+  noModel: '未选模型',
+  noSecret: (name: string) => `缺少密钥 ${name}`,
+};
+const en: typeof zh = {
+  profileObject: 'Model configuration must be an object',
+  modelRequired: 'Model name cannot be empty',
+  thinkingBoolean: 'Reasoning switch must be a boolean',
+  tierUnsupported: (title: string) => `${title} does not support this reasoning tier`,
+  effortString: 'Reasoning effort must be a non-empty string',
+  effortWithoutThinking: 'Reasoning effort cannot be set while reasoning is off',
+  temperatureRange: 'temperature must be between 0 and 2',
+  positiveInteger: (field: string) => `${field} must be a positive integer`,
+  optionsObject: 'Native options must be an object',
+  kindChange: 'An instance cannot change its provider module type',
+  baseUrlFormat: 'Provider URL must be an HTTP(S) URL without credentials',
+  secretName: 'Secret reference must be an environment variable name',
+  multimodalBoolean: 'Multimodal switch must be a boolean',
+  serviceTierString: 'Service tier must be a string',
+  serviceTierUnsupported: (title: string, tier: string) =>
+    `${title} does not support service tier ${tier}`,
+  pricingArray: 'Pricing must be an array',
+  rulesArray: 'Pricing rules must be an array',
+  ruleShape: 'A pricing rule needs a meter and a non-negative rate',
+  unitRequired: 'Unit cannot be empty',
+  tokenUnit: 'Standard token meters must use the token unit',
+  bandsArray: 'Input bands must be an array',
+  bandsIncreasing: 'Input band thresholds must be strictly increasing and greater than 0',
+  modelsRequired: 'A quote needs explicit model names or *',
+  currencyRequired: 'Quote currency cannot be empty',
+  basisValue: 'Quote basis must be marginal or equivalent',
+  sourceRequired: 'A quote needs a source',
+  tiersObject: 'Service tier pricing must be an object',
+  tierNameRequired: 'Service tier name cannot be empty',
+  tierRules: 'Service tier pricing needs a rules object',
+  noModel: 'No model selected',
+  noSecret: (name: string) => `Missing secret ${name}`,
+};
+export const text = (language: Language) => pick(language, { zh, en });

package/src/providers/transport/chat.ts

@@ -0,0 +1,156 @@
+import type { ModelSpec, ToolSchema, Logger } from '../../core/types.ts';
+import type { NativeChatMessage } from './native-types.ts';
+import { BaseProvider } from '../base.ts';
+import type { Request } from '../../protocol/open-responses/index.ts';
+import { GenerationError, type GenerateOptions, type Generation, type ResponseClient } from '../../core/generation.ts';
+import { generate } from './response-http.ts';
+import { ChatResponseAssembly, parseChatResponse, type ResponseAssembly } from './response-assembly.ts';
+import { nativeChatInput, requestSpec, requestTools } from './native-input.ts';
+
+const INFLIGHT_ALERT_WINDOW_MS = 60_000;
+const INFLIGHT_ALERT_MIN = 2;
+
+export interface StreamFailureInfo {
+  model: string;
+  /** 调用方的 session 声明 id;调用方没报就缺席。 */
+  role?: string;
+  /** 同一 (model, role) 上连续第几次在途生成失败(成功即清零)。 */
+  streak: number;
+  /** Elapsed time from stream start to failure, in milliseconds. */
+  elapsedMs: number;
+  /** LLMError.status;0 = 流内失败,不是 HTTP 码。 */
+  status: number;
+  requestId: string | null;
+  /** 完整的上游失败事件，用于诊断。 */
+  body: string;
+  message: string;
+  diagnose: ResponseClient['respond'];
+}
+
+/** 传输适配器对流内失败的处理决定。 */
+export interface StreamFailureVerdict {
+  /** false 表示停止重试并抛出本次错误。 */
+  retry: boolean;
+  /** 可选的诊断说明，追加到通用断流日志。 */
+  note?: string;
+}
+export abstract class OpenAIHttpClient extends BaseProvider {
+  protected buildResponseBody(request: Request, options: GenerateOptions): Record<string, unknown> {
+    const body = this.buildBody(requestSpec(request, options), nativeChatInput(request, options), requestTools(request), options.sessionId);
+    for (const key of ['top_p', 'presence_penalty', 'frequency_penalty', 'parallel_tool_calls'] as const) if (request[key] !== undefined) body[key] = request[key];
+    if (request.tool_choice != null) {
+      const choice = request.tool_choice;
+      if (typeof choice === 'string') body.tool_choice = choice;
+      else if (choice.type === 'function') body.tool_choice = { type: 'function', function: { name: choice.name } };
+      else throw new Error('Native Chat provider cannot map this tool_choice');
+    }
+    if (request.text?.format) {
+      const format = request.text.format;
+      body.response_format = format.type === 'json_schema' ? { type: 'json_schema', json_schema: { name: format.name, schema: format.schema, description: format.description, strict: format.strict } } : format;
+    }
+    if (options.onEvent) this.applyStreamFlags(body);
+    return body;
+  }
+
+  protected responseAssembly(request: Request): ResponseAssembly { return new ChatResponseAssembly(request); }
+
+  protected parseResponse(raw: unknown, request: Request): ReturnType<typeof parseChatResponse> { return parseChatResponse(raw, request); }
+
+  async respond(request: Request, options: GenerateOptions = {}): Promise<Generation> {
+    const origin = options.origin ?? { instance: this.constructor.name, module: this.constructor.name,
+      model: request.model ?? '', compatibilityDomain: this.baseUrl };
+    const key = OpenAIHttpClient.streakKey(request.model ?? '', options.role);
+    return generate(request, options, origin, {
+      url: `${this.baseUrl}${this.chatPath}`, body: this.buildResponseBody(request, options),
+      headers: () => this.headers(), refresh: () => this.onAuthError(),
+      assembly: () => this.responseAssembly(request), parse: raw => this.parseResponse(raw, request), log: this.log,
+      succeeded: () => { if (!options.diagnostic) this.inflightStreak.delete(key); },
+      failure: async (info, record) => {
+        const streak = (this.inflightStreak.get(key) ?? 0) + 1;
+        this.inflightStreak.set(key, streak);
+        this.noteInflightFailure({ ...info, streak });
+        const verdict = await this.judgeStreamFailure({ ...info, streak, diagnose: async (probe, probeOptions) => {
+          try {
+            const signals = [options.signal, probeOptions?.signal].filter((signal): signal is AbortSignal => Boolean(signal));
+            const result = await this.respond(probe, { ...options, onEvent: undefined, context: undefined, ...probeOptions,
+              signal: signals.length ? AbortSignal.any(signals) : undefined, diagnostic: true });
+            record(result.attempts);
+            return result;
+          } catch (error) {
+            if (error instanceof GenerationError) record(error.attempts);
+            throw error;
+          }
+        } });
+        this.log.warn('LLM 生成阶段中断：连续失败 ' + streak + ' 次，开流后 ' + (info.elapsedMs / 1000).toFixed(1) + ' 秒' + (verdict.note ? ';' + verdict.note : ''), info);
+        return verdict.retry;
+      },
+    });
+  }
+  protected baseUrl: string;
+  protected log: Logger;
+  /** 相对 baseUrl 的端点路径，可由适配器覆盖。 */
+  protected chatPath = '/chat/completions';
+  /** 同一 (model, role) 上的连续在途生成失败数;成功即清零。 */
+  private inflightStreak = new Map<string, number>();
+  /** 在途生成失败的时刻表,只用于频次告警(见 noteInflightFailure)。 */
+  private inflightFailAt: number[] = [];
+
+  constructor(baseUrl: string, log: Logger) {
+    super();
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.log = log;
+  }
+
+  private static streakKey(model: string, role?: string): string {
+    return `${model}::${role ?? ''}`;
+  }
+
+  /** 流内失败后调用；适配器可禁用该次重试，默认允许。 */
+  protected async judgeStreamFailure(_info: StreamFailureInfo): Promise<StreamFailureVerdict> {
+    return { retry: true };
+  }
+
+  /**
+   * 记录在途生成失败，窗口内达到密度门槛时发送操作员告警；仅观察，不自动处置上游或会话。
+   */
+  private noteInflightFailure(info: Omit<StreamFailureInfo, 'diagnose'>): void {
+    const now = Date.now();
+    this.inflightFailAt.push(now);
+    const cutoff = now - INFLIGHT_ALERT_WINDOW_MS;
+    while (this.inflightFailAt.length > 0 && this.inflightFailAt[0] < cutoff) this.inflightFailAt.shift();
+    if (this.inflightFailAt.length < INFLIGHT_ALERT_MIN) return;
+    this.log.warn(
+      `[告警] ${INFLIGHT_ALERT_WINDOW_MS / 1000} 秒内第 ${this.inflightFailAt.length} 次在途生成失败` +
+        `；请检查请求错误与上游状态`,
+      {
+        model: info.model,
+        ...(info.role ? { role: info.role } : {}),
+        status: info.status,
+        ...(info.requestId ? { requestId: info.requestId } : {}),
+      },
+    );
+  }
+
+  /** 方言请求体(不含 stream 字段;流式路径自行追加)。 */
+  protected abstract buildBody(
+    spec: ModelSpec,
+    messages: NativeChatMessage[],
+    tools?: ToolSchema[],
+    sessionId?: string,
+  ): Record<string, unknown>;
+
+  /** 每次请求的 HTTP 头(含鉴权,若有)。可异步:OAuth 方言在这里等一次临期刷新。 */
+  protected abstract headers(): Record<string, string> | Promise<Record<string, string>>;
+
+  /** 401/403 后调用，返回 true 时刷新后重试一次；默认返回 false。 */
+  protected async onAuthError(): Promise<boolean> {
+    return false;
+  }
+
+  /** 请求体上开流的字段。缺省是 OpenAI chat/completions 的写法。 */
+  protected applyStreamFlags(body: Record<string, unknown>): void {
+    body.stream = true;
+    body.stream_options = { include_usage: true };
+  }
+
+}

package/src/providers/transport/errors.ts

@@ -0,0 +1,48 @@
+export class LLMError extends Error {
+  status: number;
+  body: string;
+  constructor(message: string, status: number, body: string) {
+    super(message);
+    this.name = 'LLMError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/**
+ * Whether an upstream rejection says the input exceeded the model's context. Status 0 is an
+ * in-stream failure event; 400/413 are the request-rejection codes. The body patterns cover
+ * the OpenAI `context_length_exceeded` code, DeepSeek's "maximum context length" message
+ * and llama-server's "exceeds the available context size".
+ */
+export function isContextOverflow(error: { status: number; body: string }): boolean {
+  if (error.status !== 0 && error.status !== 400 && error.status !== 413) return false;
+  return /context_length_exceeded|context length|context size|context window|maximum context|prompt is too long|input is too long|too many tokens/i.test(error.body);
+}
+
+/** 上游请求 id 拼进错误消息的固定形状(没有就什么都不拼)。 */
+export function reqIdSuffix(requestId: string | null | undefined): string {
+  return requestId ? ` [req=${requestId}]` : '';
+}
+
+export function abortError(signal: AbortSignal): LLMError {
+  const reason = signal.reason;
+  const detail = reason instanceof Error ? reason.message : String(reason ?? '调用方取消');
+  return new LLMError(`LLM请求已取消: ${detail}`, 0, '');
+}
+
+export function retryDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  if (!signal) return new Promise((resolve) => setTimeout(resolve, ms));
+  if (signal.aborted) return Promise.reject(abortError(signal));
+  return new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(abortError(signal));
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+}

package/src/providers/transport/history.ts

@@ -0,0 +1,68 @@
+import type { NativeChatMessage } from './native-types.ts';
+import type { ToolSchema } from '../../core/types.ts';
+export function dropPastThinking(messages: NativeChatMessage[]): NativeChatMessage[] {
+  return messages.map((m) =>
+    m.role === 'assistant' && m.reasoning_content && !m.head
+      ? { ...m, reasoning_content: '' }
+      : m,
+  );
+}
+
+/** 线上不带 blobs 字段:句柄是 core 内部形态,分片渲染(若有)另行处理。 */
+export function dropBlobsField(m: NativeChatMessage): NativeChatMessage {
+  if (m.blobs === undefined) return m;
+  const { blobs: _drop, ...rest } = m;
+  return rest as NativeChatMessage;
+}
+
+export function dropHeadMark(m: NativeChatMessage): NativeChatMessage {
+  return { role: m.role, content: m.content,
+    ...(m.reasoning_content !== undefined ? { reasoning_content: m.reasoning_content } : {}),
+    ...(m.tool_calls ? { tool_calls: m.tool_calls } : {}),
+    ...(m.tool_call_id ? { tool_call_id: m.tool_call_id } : {}), ...(m.parts ? { parts: m.parts } : {}) };
+}
+
+export interface CompatMediaOptions {
+  enabled: () => boolean;
+  read: (ref: string) => Buffer | null;
+}
+
+/** OpenAI function 格式的 tools 段(各 chat 方言共用)。 */
+export function mapTools(tools?: ToolSchema[]): Array<Record<string, unknown>> | undefined {
+  if (!tools || tools.length === 0) return undefined;
+  return tools.map((t) => ({
+    type: 'function',
+    function: { name: t.name, description: t.description, parameters: t.parameters },
+  }));
+}
+
+/**
+ * 渲染 Chat 请求消息，移除内部 blobs 字段。仅在 keepReasoning 时保留非空 reasoning_content。
+ * 启用媒体时将可读取附件转换为 data URL 内容块；无法读取的附件跳过，原文本引用仍保留。
+ */
+export function renderMessagesWithMedia(
+  messages: NativeChatMessage[],
+  media?: CompatMediaOptions,
+  opts?: { keepReasoning?: boolean },
+): Array<Record<string, unknown>> {
+  const renderMedia = media?.enabled() === true ? media : undefined;
+  return messages.map((m) => {
+    const refs = m.blobs;
+    const { reasoning_content: _r, parts: _parts, ...rest } = dropHeadMark(m);
+    const base = { ...rest, content: m.parts ?? m.content } as Record<string, unknown>;
+    if (opts?.keepReasoning && m.reasoning_content) base.reasoning_content = m.reasoning_content;
+    if (!renderMedia || !refs?.length) return base;
+    const parts: Array<Record<string, unknown>> = m.parts ? [...m.parts] : [{ type: 'text', text: m.content }];
+    let attached = false;
+    for (const r of refs) {
+      const bytes = renderMedia.read(r.handle);
+      if (!bytes) continue;
+      attached = true;
+      parts.push({
+        type: 'image_url',
+        image_url: { url: `data:${r.mime};base64,${bytes.toString('base64')}` },
+      });
+    }
+    return attached ? { ...base, content: parts } : base;
+  });
+}

package/src/providers/transport/native-input.ts

@@ -0,0 +1,83 @@
+import type { NativeChatMessage } from './native-types.ts';
+import type { ModelSpec, ToolSchema } from '../../core/types.ts';
+import type { Request } from '../../protocol/open-responses/index.ts';
+import { ResponseProtocolError } from '../../protocol/open-responses/stream.ts';
+import { itemText, record, type ContextRecord } from '../../protocol/open-responses/context.ts';
+import type { GenerateOptions } from '../../core/generation.ts';
+
+export function requestSpec(request: Request, options: GenerateOptions): ModelSpec {
+  return { ...options.nativeSpec, model: request.model ?? options.nativeSpec?.model ?? '',
+    thinking: options.nativeSpec?.thinking ?? request.reasoning?.effort !== 'none',
+    ...(request.reasoning?.effort && request.reasoning.effort !== 'none' ? { reasoningEffort: request.reasoning.effort } : {}),
+    ...(options.nativeSpec?.reasoningEffort === 'max' ? { reasoningEffort: 'max' } : {}),
+    ...(request.temperature != null ? { temperature: request.temperature } : {}),
+    ...(request.max_output_tokens != null ? { maxTokens: request.max_output_tokens } : {}),
+  };
+}
+
+export function requestTools(request: Request): ToolSchema[] | undefined {
+  return request.tools?.map(tool => ({ name: tool.name, description: tool.description ?? '', parameters: tool.parameters ?? {} }));
+}
+
+export function requestContext(request: Request, options: GenerateOptions): readonly ContextRecord[] {
+  if (options.context) return options.context;
+  if (typeof request.input === 'string') return [record({ type: 'message', role: 'user', content: request.input })];
+  return (request.input ?? []).map(item => record(item));
+}
+
+function nativeParts(entry: ContextRecord): Array<Record<string, unknown>> | undefined {
+  const item = entry.item;
+  const content = item.type === 'message' ? item.content : item.type === 'function_call_output' ? item.output : undefined;
+  if (!Array.isArray(content) || content.every(part => 'text' in part || part.type === 'refusal')) return undefined;
+  return content.map(part => {
+    if ('text' in part) return { type: 'text', text: part.text };
+    if (part.type === 'input_image') {
+      if (!part.image_url) throw new ResponseProtocolError('Native Chat images require image_url');
+      return { type: 'image_url', image_url: { url: part.image_url, ...(part.detail ? { detail: part.detail } : {}) } };
+    }
+    if (part.type === 'input_file') {
+      if (!('file_data' in part) || !part.file_data) throw new ResponseProtocolError('Native Chat files require inline file_data');
+      return { type: 'file', file: { ...(part.filename ? { filename: part.filename } : {}), file_data: part.file_data } };
+    }
+    throw new ResponseProtocolError('Unsupported native Chat content part: ' + part.type);
+  });
+}
+
+/** Chat Completions has one assistant envelope for adjacent reasoning, text and function calls. */
+export function nativeChatInput(request: Request, options: GenerateOptions): NativeChatMessage[] {
+  const messages: NativeChatMessage[] = [];
+  if (request.instructions) messages.push({ role: 'system', content: request.instructions });
+  let assistant: NativeChatMessage | null = null;
+  const ensureAssistant = (entry: ContextRecord): NativeChatMessage => {
+    if (!assistant) {
+      assistant = { role: 'assistant', content: '', ...(entry.context.head ? { head: true } : {}) };
+      messages.push(assistant);
+    }
+    return assistant;
+  };
+  let group: string | number | undefined;
+  for (const entry of requestContext(request, options)) {
+    const nextGroup = entry.context.responseId;
+    if (nextGroup !== undefined && nextGroup !== group) assistant = null;
+    group = nextGroup;
+    const item = entry.item;
+    if (item.type === 'reasoning') {
+      const target = ensureAssistant(entry);
+      target.reasoning_content = (target.reasoning_content ?? '') + itemText(item);
+    } else if (item.type === 'function_call') {
+      const target = ensureAssistant(entry);
+      (target.tool_calls ??= []).push({ id: item.call_id, type: 'function', function: { name: item.name, arguments: item.arguments } });
+    } else if (item.type === 'function_call_output') {
+      assistant = null;
+      messages.push({ role: 'tool', content: itemText(item), parts: nativeParts(entry), tool_call_id: item.call_id, blobs: entry.context.blobs });
+    } else if (item.type === 'message') {
+      if (item.role === 'assistant') {
+        ensureAssistant(entry).content += itemText({ ...item, type: 'message' });
+      } else {
+        assistant = null;
+        messages.push({ role: item.role === 'developer' ? 'system' : item.role, content: itemText({ ...item, type: 'message' }), parts: nativeParts(entry), blobs: entry.context.blobs });
+      }
+    } else throw new Error(`Native Chat provider cannot replay ${item.type}`);
+  }
+  return messages;
+}

package/src/providers/transport/native-types.ts

@@ -0,0 +1,13 @@
+import type { BlobRef } from '../../core/types.ts';
+
+/** Chat Completions request envelope, used only inside native provider adapters. */
+export interface NativeChatMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  parts?: Array<Record<string, unknown>>;
+  reasoning_content?: string;
+  tool_calls?: { id: string; type: 'function'; function: { name: string; arguments: string } }[];
+  tool_call_id?: string;
+  blobs?: BlobRef[];
+  head?: true;
+}