cortico 0.1.0

package/src/providers/transport/response-assembly.ts

@@ -0,0 +1,191 @@
+import { createResponse, type OutputItem, type Request, type Response, type StreamEvent } from '../../protocol/open-responses/index.ts';
+import { ResponseAccumulator, ResponseProtocolError } from '../../protocol/open-responses/stream.ts';
+import { standardUsage, unknownMeters, type TokenMeters } from '../../core/generation.ts';
+import { chatMeters, responseMeters } from './response-meters.ts';
+
+export interface ResponseAssembly {
+  feed(payload: unknown, emit: (event: StreamEvent) => void): void;
+  finish(emit: (event: StreamEvent) => void): Response;
+  snapshot(): Response | null;
+  meters(): TokenMeters;
+  serviceTier(): string | null;
+}
+
+/**
+ * Validate native Responses Items before notifying observers.
+ * Normalize response.reasoning_text.* to the schema name response.reasoning.* before validation.
+ */
+export class NativeResponseAssembly implements ResponseAssembly {
+  private readonly accumulator = new ResponseAccumulator();
+  private usage = unknownMeters();
+  private tier: string | null = null;
+  feed(payload: unknown, emit: (event: StreamEvent) => void): void {
+    if (!payload || typeof payload !== 'object') throw new ResponseProtocolError('Invalid native Responses event');
+    if ('type' in payload && (payload.type === 'response.reasoning_text.delta' || payload.type === 'response.reasoning_text.done'))
+      payload = { ...payload, type: payload.type.replace('reasoning_text', 'reasoning') };
+    let event = payload as StreamEvent;
+    if ('response' in event) {
+      const raw = event.response;
+      if (!raw || typeof raw.id !== 'string' || typeof raw.model !== 'string' || !Array.isArray(raw.output)) throw new ResponseProtocolError('Invalid native Responses resource');
+      if (typeof raw.service_tier === 'string') this.tier = raw.service_tier;
+      if (raw.usage) this.usage = responseMeters(raw.usage);
+      event = { ...event, response: { ...createResponse(raw.id, { model: raw.model }), ...raw, usage: standardUsage(this.usage) } };
+    }
+    this.accumulator.accept(event);
+    emit(event);
+    if (event.type === 'error') throw new ResponseProtocolError(`Native response error: ${JSON.stringify(event)}`);
+  }
+  finish(): Response { return this.accumulator.finish(); }
+  snapshot(): Response | null { return this.accumulator.snapshot(); }
+  serviceTier(): string | null { return this.tier; }
+  meters(): TokenMeters { return structuredClone(this.usage); }
+}
+
+type NativeChunk = {
+  id?: string; model?: string; service_tier?: string;
+  choices?: Array<{ index?: number; finish_reason?: string | null; delta?: {
+    content?: string | null; refusal?: string | null; reasoning_content?: string | null;
+    tool_calls?: Array<{ index: number; id?: string; function?: { name?: string; arguments?: string } }>;
+  } }>;
+  usage?: Record<string, unknown> | null;
+};
+type MutableOutput = { id: string; type: string; status?: string; content?: any[]; summary?: any[]; call_id?: string; name?: string; arguments?: string; role?: string };
+
+/** Chat's finish_reason closes its Items; a new tool index never closes a previous call. */
+export class ChatResponseAssembly implements ResponseAssembly {
+  private readonly response: Response;
+  private readonly accumulator = new ResponseAccumulator();
+  private sequence = 0;
+  private started = false;
+  private finishReason: string | null = null;
+  private usage = unknownMeters();
+  private tier: string | null = null;
+  private readonly calls = new Map<number, number>();
+  private readonly textSlots = new Map<string, number>();
+  private readonly pendingCalls = new Map<number, NonNullable<NonNullable<NonNullable<NativeChunk['choices']>[number]['delta']>['tool_calls']>>();
+  private readonly output: MutableOutput[] = [];
+  /** The Item that received the last delta is the one a length or filter stop cut short. */
+  private lastTouched: number | null = null;
+
+  constructor(request: Request) { this.response = createResponse(`resp_${crypto.randomUUID()}`, request); }
+
+  private send(event: Record<string, unknown>, emit: (event: StreamEvent) => void): void {
+    const complete = structuredClone({ ...event, sequence_number: this.sequence++ }) as StreamEvent;
+    this.accumulator.accept(complete);
+    emit(complete);
+  }
+  private start(chunk: NativeChunk, emit: (event: StreamEvent) => void): void {
+    if (this.started) return;
+    if (chunk.id) this.response.id = chunk.id;
+    if (chunk.model) this.response.model = chunk.model;
+    this.send({ type: 'response.created', response: this.response }, emit);
+    this.started = true;
+  }
+  private add(index: number, item: MutableOutput, emit: (event: StreamEvent) => void): void {
+    if (this.output[index]) throw new ResponseProtocolError('Native Chat output indices overlap');
+    this.output[index] = item;
+    this.send({ type: 'response.output_item.added', output_index: index, item }, emit);
+  }
+  private text(kind: 'reasoning' | 'content' | 'refusal', delta: string, emit: (event: StreamEvent) => void): void {
+    let index = this.textSlots.get(kind);
+    if (index === undefined) {
+      index = this.output.length;
+      const item = kind === 'reasoning'
+        ? { type: 'reasoning', id: `rs_${crypto.randomUUID()}`, summary: [], content: [] }
+        : { type: 'message', id: `msg_${crypto.randomUUID()}`, role: 'assistant', status: 'in_progress', content: [] };
+      this.add(index, item, emit);
+      this.textSlots.set(kind, index);
+      const part = kind === 'reasoning' ? { type: 'reasoning_text', text: '' }
+        : kind === 'refusal' ? { type: 'refusal', refusal: '' } : { type: 'output_text', text: '', annotations: [] };
+      this.send({ type: 'response.content_part.added', output_index: index, item_id: item.id, content_index: 0, part }, emit);
+      this.output[index].content = [part];
+    }
+    const item = this.output[index];
+    this.send({ type: kind === 'reasoning' ? 'response.reasoning.delta' : kind === 'refusal' ? 'response.refusal.delta' : 'response.output_text.delta',
+      output_index: index, item_id: item.id, content_index: 0, delta, ...(kind === 'content' ? { logprobs: [] } : {}) }, emit);
+    const field = kind === 'refusal' ? 'refusal' : 'text';
+    item.content![0][field] += delta;
+    this.lastTouched = index;
+  }
+  feed(payload: unknown, emit: (event: StreamEvent) => void): void {
+    const chunk = payload as NativeChunk;
+    this.start(chunk, emit);
+    if (chunk.usage) this.usage = chatMeters(chunk.usage);
+    if (chunk.service_tier) this.response.service_tier = this.tier = chunk.service_tier;
+    const choice = chunk.choices?.[0];
+    if (!choice) return;
+    if (choice.index !== undefined && choice.index !== 0) throw new ResponseProtocolError('Multiple Chat choices are unsupported');
+    const delta = choice.delta;
+    if (delta?.reasoning_content) this.text('reasoning', delta.reasoning_content, emit);
+    if (delta?.content) this.text('content', delta.content, emit);
+    if (delta?.refusal) this.text('refusal', delta.refusal, emit);
+    for (const call of delta?.tool_calls ?? []) {
+      if (!Number.isInteger(call.index) || call.index < 0) throw new ResponseProtocolError('Invalid native tool index');
+      const pending = this.pendingCalls.get(call.index) ?? [];
+      pending.push(call);
+      this.pendingCalls.set(call.index, pending);
+    }
+    for (const nativeIndex of [...this.pendingCalls.keys()].sort((a, b) => a - b)) {
+      if (!this.calls.has(nativeIndex) && nativeIndex !== this.calls.size) break;
+      for (const call of this.pendingCalls.get(nativeIndex)!) {
+        let index = this.calls.get(call.index);
+        if (index === undefined) {
+          if (!call.id || !call.function?.name) throw new ResponseProtocolError('Native function call lacks identity');
+          index = this.output.length;
+          this.calls.set(call.index, index);
+          this.add(index, { type: 'function_call', id: `fc_${crypto.randomUUID()}`, call_id: call.id,
+            name: call.function.name, arguments: '', status: 'in_progress' }, emit);
+        }
+        const item = this.output[index];
+        if ((call.id && call.id !== item.call_id) || (call.function?.name && call.function.name !== item.name)) throw new ResponseProtocolError('Native function identity changed');
+        const fragment = call.function?.arguments;
+        if (fragment) {
+          this.send({ type: 'response.function_call_arguments.delta', output_index: index, item_id: item.id, delta: fragment }, emit);
+          item.arguments += fragment;
+        }
+        this.lastTouched = index;
+      }
+      this.pendingCalls.delete(nativeIndex);
+    }
+    if (choice.finish_reason) this.finishReason = choice.finish_reason;
+  }
+  /** A length or content-filter stop cuts only the Item that was still being written; earlier Items are complete. */
+  finish(emit: (event: StreamEvent) => void): Response {
+    if (!this.finishReason) throw new ResponseProtocolError('Chat transport ended without finish_reason');
+    if (this.pendingCalls.size) throw new ResponseProtocolError('Missing native function index');
+    const incomplete = this.finishReason === 'length' || this.finishReason === 'content_filter';
+    for (let index = 0; index < this.output.length; index++) {
+      const item = this.output[index];
+      if (!item) throw new ResponseProtocolError('Missing native function index');
+      if (item.type === 'function_call') {
+        this.send({ type: 'response.function_call_arguments.done', output_index: index, item_id: item.id, arguments: item.arguments }, emit);
+      } else {
+        const part = item.content![0];
+        this.send({ type: 'response.content_part.done', output_index: index, item_id: item.id, content_index: 0, part }, emit);
+      }
+      if (item.type !== 'reasoning') item.status = incomplete && index === this.lastTouched ? 'incomplete' : 'completed';
+      this.send({ type: 'response.output_item.done', output_index: index, item }, emit);
+    }
+    this.response.output = this.output as OutputItem[];
+    this.response.usage = standardUsage(this.usage);
+    this.response.status = incomplete ? 'incomplete' : 'completed';
+    this.response.completed_at = Math.floor(Date.now() / 1000);
+    this.response.incomplete_details = incomplete ? { reason: this.finishReason === 'length' ? 'max_output_tokens' : 'content_filter' } : null;
+    this.send({ type: `response.${this.response.status}`, response: this.response }, emit);
+    return this.accumulator.finish();
+  }
+  snapshot(): Response | null { return this.accumulator.snapshot(); }
+  serviceTier(): string | null { return this.tier; }
+  meters(): TokenMeters { return structuredClone(this.usage); }
+}
+
+export function parseChatResponse(raw: unknown, request: Request): { response: Response; meters: TokenMeters; serviceTier: string | null } {
+  const data = raw as { id?: string; model?: string; usage?: Record<string, unknown>; choices?: Array<{ index?: number; finish_reason?: string | null; message?: Record<string, any> }> };
+  const choice = data.choices?.[0] as { message?: Record<string, any>; finish_reason?: string | null } | undefined;
+  if (!choice?.message) throw new ResponseProtocolError('Native Chat response lacks choices[0].message');
+  const assembler = new ChatResponseAssembly(request);
+  assembler.feed({ ...data, choices: [{ index: 0, delta: { ...choice.message,
+    tool_calls: choice.message.tool_calls?.map((call: any, index: number) => ({ ...call, index })) }, finish_reason: choice.finish_reason }] }, () => {});
+  const response = assembler.finish(() => {});
+  return { response, meters: assembler.meters(), serviceTier: assembler.serviceTier() };
+}

package/src/providers/transport/response-http.ts

@@ -0,0 +1,196 @@
+import type { Logger } from '../../core/types.ts';
+import type { Request, Response, StreamEvent } from '../../protocol/open-responses/index.ts';
+import type { ItemOrigin } from '../../protocol/open-responses/context.ts';
+import { GenerationError, priceUsage, unknownMeters, type GenerateOptions, type Generation, type ProviderAttempt, type PriceSnapshot, type TokenMeters } from '../../core/generation.ts';
+import { ResponseProtocolError } from '../../protocol/open-responses/stream.ts';
+import { LLMError, abortError, retryDelay, reqIdSuffix } from './errors.ts';
+import type { ResponseAssembly } from './response-assembly.ts';
+
+export interface ResponseTransport {
+  url: string;
+  body: Record<string, unknown>;
+  headers(): Record<string, string> | Promise<Record<string, string>>;
+  refresh(): Promise<boolean>;
+  assembly(): ResponseAssembly;
+  parse(raw: unknown): { response: Response; meters: TokenMeters; serviceTier: string | null };
+  failure(info: { model: string; role?: string; elapsedMs: number; status: number; requestId: string | null; body: string; message: string }, record: (attempts: ProviderAttempt[]) => void): Promise<boolean>;
+  succeeded(): void;
+  log: Logger;
+}
+
+/** SSE framing is independent of packet and line boundaries. */
+export class EventDecoder {
+  private buffer = '';
+  private data: string[] = [];
+  feed(text: string): string[] {
+    this.buffer += text;
+    const events: string[] = [];
+    for (;;) {
+      const newline = this.buffer.indexOf('\n');
+      if (newline < 0) break;
+      const line = this.buffer.slice(0, newline).replace(/\r$/, '');
+      this.buffer = this.buffer.slice(newline + 1);
+      if (line === '') {
+        if (this.data.length) events.push(this.data.join('\n'));
+        this.data = [];
+      } else if (line.startsWith('data:')) this.data.push(line.slice(5).replace(/^ /, ''));
+    }
+    return events;
+  }
+}
+
+function irreversible(event: StreamEvent): boolean {
+  return event.type === 'response.output_text.delta' || event.type === 'response.refusal.delta'
+    || event.type === 'response.function_call_arguments.delta'
+    || (event.type === 'response.output_item.added' && event.item?.type === 'function_call');
+}
+
+/** 带内容的事件:增量,或输出项的开合。keepalive 帧与空事件不算。 */
+function carriesContent(event: StreamEvent): boolean {
+  return 'delta' in event || event.type === 'response.output_item.added' || event.type === 'response.output_item.done';
+}
+
+/** 首包等待上限：流式 300 秒，非流式 120 秒。 */
+const FIRST_RESPONSE_MS = { streaming: 300_000, unary: 120_000 } as const;
+/** 帧空闲:连续这么久一个字节都没来。 */
+const FRAME_IDLE_MS = 120_000;
+/**
+ * 内容事件的空闲期限；keepalive 和空 delta 不重置它。
+ * 该计时器独立于字节接收计时，以覆盖持续收到空帧的响应。
+ */
+const CONTENT_IDLE_MS = 300_000;
+
+/** Every fetch attempt produces its own immutable metering and price snapshot. */
+export async function generate(request: Request, options: GenerateOptions, origin: ItemOrigin, transport: ResponseTransport): Promise<Generation> {
+  const generationId = crypto.randomUUID();
+  const attempts: ProviderAttempt[] = [];
+  let lastError: unknown;
+  let partial: Response | null = null;
+  let authRetried = false;
+  const delays = options.diagnostic ? [] : [1000, 4000, 10000];
+  const fail = (error: unknown): GenerationError => new GenerationError((error instanceof Error ? error.message : String(error)) + reqIdSuffix(attempts.filter(attempt => attempt.purpose !== 'diagnostic').at(-1)?.requestId), attempts,
+    partial, origin, error instanceof LLMError ? error.status : 0, error instanceof LLMError ? error.body : '', { cause: error });
+  for (let ordinal = 0; ordinal <= delays.length; ordinal++) {
+    try {
+      if (options.signal?.aborted) throw abortError(options.signal);
+      if (ordinal) await retryDelay(delays[ordinal - 1], options.signal);
+    } catch (error) { throw fail(error); }
+    const attempt: ProviderAttempt = {
+      id: crypto.randomUUID(), generationId, ordinal, origin: structuredClone(origin), startedAt: new Date().toISOString(), elapsedMs: 0,
+      requestId: null, responseId: null, outcome: 'failed', status: null, serviceTier: null, requestedServiceTier: typeof transport.body.service_tier === 'string' ? transport.body.service_tier : request.service_tier ?? null, purpose: options.diagnostic ? 'diagnostic' : 'generation', meters: unknownMeters(), charges: [],
+    };
+    let quotes: readonly PriceSnapshot[] = [];
+    const started = Date.now();
+    const controller = new AbortController();
+    const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+    const streaming = Boolean(options.onEvent);
+    let timer = setTimeout(() => controller.abort(new Error('Provider first response timeout')), streaming ? FIRST_RESPONSE_MS.streaming : FIRST_RESPONSE_MS.unary);
+    let contentTimer: ReturnType<typeof setTimeout> | null = null;
+    const touchContent = (): void => {
+      if (contentTimer) clearTimeout(contentTimer);
+      contentTimer = setTimeout(() => controller.abort(new Error('Provider stream content idle timeout')), CONTENT_IDLE_MS);
+    };
+    let committed = false;
+    let characters = 0;
+    let runaway = false;
+    let observed = false;
+    const assembly = transport.assembly();
+    let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+    let sent = false;
+    let finishedAt: number | null = null;
+    const diagnostics: ProviderAttempt[] = [];
+    partial = null;
+    const forward = (event: StreamEvent): void => {
+      observed = true;
+      if (carriesContent(event)) touchContent();
+      if ('delta' in event && typeof event.delta === 'string') characters += event.delta.length;
+      if (irreversible(event)) committed = true;
+      if (!options.signal?.aborted) options.onEvent?.(event);
+      if (characters > (request.max_output_tokens ?? 32768) * 12) {
+        runaway = true;
+        controller.abort();
+        throw new LLMError('Provider exceeded the output character limit', 0, '');
+      }
+    };
+    try {
+      const headers = await transport.headers();
+      if (options.signal?.aborted) throw abortError(options.signal);
+      attempt.startedAt = new Date().toISOString();
+      quotes = structuredClone(options.quote?.({ startedAt: attempt.startedAt, requestedServiceTier: attempt.requestedServiceTier ?? null }) ?? []);
+      sent = true;
+      const response = await fetch(transport.url, { method: 'POST', body: JSON.stringify(transport.body), headers, signal });
+      attempt.status = response.status;
+      attempt.requestId = response.headers.get('x-request-id');
+      if (!response.ok) {
+        const error = new LLMError(`LLM API ${response.status}`, response.status, await response.text());
+        if (!options.diagnostic && (response.status === 401 || response.status === 403) && !authRetried && await transport.refresh()) {
+          authRetried = true;
+          lastError = error;
+          continue;
+        }
+        throw error;
+      }
+      if (streaming) {
+        if (!response.body) throw new LLMError('Streaming response has no body', response.status, '');
+        reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        const frames = new EventDecoder();
+        touchContent();
+        stream: for (;;) {
+          const chunk = await reader.read();
+          clearTimeout(timer);
+          timer = setTimeout(() => controller.abort(new Error('Provider stream idle timeout')), FRAME_IDLE_MS);
+          if (chunk.done) break;
+          for (const payload of frames.feed(decoder.decode(chunk.value, { stream: true }))) {
+            if (payload === '[DONE]') break stream;
+            assembly.feed(JSON.parse(payload), forward);
+          }
+        }
+        partial = assembly.finish(forward);
+        attempt.meters = assembly.meters();
+        attempt.serviceTier = assembly.serviceTier();
+      } else {
+        const parsed = transport.parse(JSON.parse(await response.text()));
+        partial = parsed.response;
+        attempt.meters = parsed.meters;
+        attempt.serviceTier = parsed.serviceTier;
+      }
+      attempt.responseId = partial.id;
+      if (partial.status === 'failed') throw new LLMError(partial.error?.message ?? partial.error?.code ?? 'Response failed', 0, JSON.stringify(partial.error));
+      if (partial.status !== 'completed' && partial.status !== 'incomplete') throw new LLMError(`Response has no terminal status: ${partial.status}`, 0, '');
+      attempt.outcome = options.signal?.aborted ? 'discarded' : partial.status;
+      transport.succeeded();
+      return { response: partial, origin, attempts };
+    } catch (error) {
+      finishedAt = Date.now();
+      if (streaming) {
+        partial = assembly.snapshot();
+        attempt.meters = assembly.meters();
+      }
+      attempt.responseId = partial?.id ?? null;
+      if (options.signal?.aborted) {
+        attempt.outcome = 'aborted';
+        lastError = abortError(options.signal);
+        break;
+      }
+      lastError = error;
+      if (!sent || committed || runaway || (!streaming && error instanceof ResponseProtocolError)) break;
+      const status = error instanceof LLMError ? error.status : 0;
+      if (status !== 0 && status !== 429 && status < 500) break;
+      if (!options.diagnostic && observed && Date.now() - started >= 20000 && !await transport.failure({
+        model: request.model ?? '', role: options.role, elapsedMs: Date.now() - started, status,
+        requestId: attempt.requestId, body: error instanceof LLMError ? error.body : '', message: String(error),
+      }, values => diagnostics.push(...values))) break;
+      transport.log.warn('Provider attempt failed; retrying', { ordinal, err: String(error) });
+    } finally {
+      clearTimeout(timer);
+      if (contentTimer) clearTimeout(contentTimer);
+      if (reader) { try { await reader.cancel(); } catch { /* The failed transport may already be closed. */ } reader.releaseLock(); }
+      attempt.elapsedMs = (finishedAt ?? Date.now()) - started;
+      attempt.charges = priceUsage(attempt.meters, quotes, attempt.serviceTier);
+      if (sent) attempts.push(attempt);
+      attempts.push(...diagnostics);
+    }
+  }
+  throw fail(lastError);
+}

package/src/providers/transport/response-meters.ts

@@ -0,0 +1,27 @@
+import { unknownMeters, type TokenMeters } from '../../core/generation.ts';
+
+/** A meter the provider did not report as a finite number stays unknown; the raw usage is kept beside it. */
+function number(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/** Native Chat Completions usage, including DeepSeek's explicit cache distribution. */
+export function chatMeters(raw: Record<string, any> | null | undefined): TokenMeters {
+  if (!raw) return unknownMeters();
+  const input = number(raw.prompt_tokens);
+  const output = number(raw.completion_tokens);
+  const cachedInput = number(raw.prompt_cache_hit_tokens ?? raw.prompt_tokens_details?.cached_tokens);
+  const uncachedInput = number(raw.prompt_cache_miss_tokens) ?? (input !== null && cachedInput !== null ? input - cachedInput : null);
+  return { input, output, total: number(raw.total_tokens) ?? (input !== null && output !== null ? input + output : null),
+    cachedInput, uncachedInput, reasoning: number(raw.completion_tokens_details?.reasoning_tokens), native: structuredClone(raw) };
+}
+
+export function responseMeters(raw: Record<string, any> | null | undefined): TokenMeters {
+  if (!raw) return unknownMeters();
+  const input = number(raw.input_tokens);
+  const output = number(raw.output_tokens);
+  const cachedInput = number(raw.input_tokens_details?.cached_tokens);
+  const uncachedInput = input !== null && cachedInput !== null ? input - cachedInput : null;
+  return { input, output, total: number(raw.total_tokens) ?? (input !== null && output !== null ? input + output : null),
+    cachedInput, uncachedInput, reasoning: number(raw.output_tokens_details?.reasoning_tokens), native: structuredClone(raw) };
+}

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

@@ -0,0 +1,56 @@
+/** Stateless native Responses input: the whole context is replayed on every request. */
+import type { Request } from '../../protocol/open-responses/index.ts';
+import { inputItem } from '../../protocol/open-responses/context.ts';
+import type { GenerateOptions } from '../../core/generation.ts';
+import { requestContext } from './native-input.ts';
+import type { CompatMediaOptions } from './history.ts';
+
+type Item = Record<string, unknown>;
+
+export interface ResponsesInputOptions {
+  media?: CompatMediaOptions;
+  /** Whether past reasoning re-enters the context; the first synthetic turn is exempt. */
+  keepThinking?: () => boolean;
+}
+
+/**
+ * Replay reasoning only when encrypted_content exists and the recorded instance, module,
+ * compatibility domain and model match this request. These are local eligibility checks.
+ * Plaintext reasoning is omitted. System and developer text is joined into instructions.
+ */
+export function responsesInput(
+  request: Request,
+  options: GenerateOptions,
+  opts: ResponsesInputOptions = {},
+): { input: Item[]; instructions: string | undefined } {
+  const input: Item[] = [];
+  const systems = request.instructions ? [request.instructions] : [];
+  for (const entry of requestContext(request, options)) {
+    const item = entry.item;
+    if (item.type === 'reasoning') {
+      if (!item.encrypted_content) continue;
+      if (!entry.context.head && opts.keepThinking?.() === false) continue;
+      const owner = entry.context.origin;
+      const current = options.origin;
+      if (!owner || !current || owner.instance !== current.instance || owner.module !== current.module
+        || owner.compatibilityDomain !== current.compatibilityDomain || owner.model !== request.model) continue;
+    }
+    if (item.type === 'message' && (item.role === 'system' || item.role === 'developer')) {
+      systems.push(typeof item.content === 'string' ? item.content : item.content.map(part => 'text' in part ? part.text : '').join(''));
+      continue;
+    }
+    const wire = inputItem(entry) as Item;
+    if (opts.media?.enabled() && entry.context.blobs?.length && (item.type === 'message' || item.type === 'function_call_output')) {
+      const field = item.type === 'message' ? 'content' : 'output';
+      const content = wire[field];
+      const parts = typeof content === 'string' ? [{ type: 'input_text', text: content }] : [...(content as Item[])];
+      for (const ref of entry.context.blobs) {
+        const bytes = opts.media.read(ref.handle);
+        if (bytes) parts.push({ type: 'input_image', image_url: `data:${ref.mime};base64,${bytes.toString('base64')}` });
+      }
+      wire[field] = parts;
+    }
+    input.push(wire);
+  }
+  return { input, instructions: systems.length ? systems.join('\n') : undefined };
+}

package/src/web/README.md

@@ -0,0 +1,84 @@
+<!-- Owner: src/web/server.ts, src/web/shared/console-protocol.ts, src/web/shared/client-panel.ts, src/web/client/console-pages/builtins/llm-settings/panel.ts -->
+
+# src/web
+
+控制台服务端、共享协议和浏览器代码。框架页面由控制台实现；World、Persona 与 Provider 通过声明贡献页面。
+服务端聚合、校验并分发声明。
+
+## 目录
+
+| 路径 | 职责 |
+|---|---|
+| `server.ts` | `WebApp`：Express、WebSocket、API 路由、静态资源和首页入口注入。 |
+| `console-pages.ts` | `ConsolePageRegistry`、`ConsoleAssets`：聚合页面与资源，读取 `dist/web/asset-manifest.json`。 |
+| `path-picker.ts` | 按平台调用本机路径选择器。 |
+| `shared/console-protocol.ts` | 页面 id、manifest、路由常量与校验规则，供服务端和浏览器共用。 |
+| `shared/client-panel.ts` | 浏览器面板接口：`ConsolePanelContext`、`ConsoleUi`、`ConsolePanel`。 |
+| `client/core/` | API、路由、生命周期、流连接、WebSocket 与语言设置。 |
+| `client/console-pages/` | 页面宿主、面板加载器、上下文与内置面板，如 `llm-settings`。 |
+| `client/features/` | 框架页面，每页实现 `FrameworkFeature`。 |
+| `client/ui/` | `ConsoleUi` 组件与图标。 |
+| `client/shell/`、`client/theme/` | 页面框架与主题。 |
+| `public/` | `index.html` 与 Tailwind 入口。 |
+
+## 协议
+
+`ConsolePageKind` 包含 `framework`、`world`、`persona`、`memory`、`llm`。贡献页 id 使用 `world:<id>`、
+`persona:<id>`、`memory:<id>` 或 `llm:<id>`；构建脚本与服务端共用 `pageIdFor()`,`memory:<id>` 的浏览器产物
+取 `persona:<id>` 那份。面板 id 在所属页内唯一。
+manifest 的 `CONSOLE_PROTOCOL_VERSION` 不匹配时，浏览器拒绝加载。
+
+`toPageManifest()` 将服务端的 `ConsolePageContribution` 转换为 `ConsolePageManifest`。
+`invoke`、`promptDocs.path`、`config.schema` 和 `storage` 不发送给浏览器；`links`、`builtin` 与资源 URL 按协议规则校验。
+链接拒绝 `javascript:`、`data:`，一页最多七盏状态灯。
+
+| 路由 | 用途 |
+|---|---|
+| `/api/console/manifest` | 页面声明。 |
+| `/api/console/lamps` | 状态灯。 |
+| `/api/console/providers/<page>/panels/<panel>/<method>` | 面板调用；GET 只对面板 `getMethods` 点名的方法开放，参数使用 query 中的 JSON 数组；POST JSON 上限为 64 MiB。 |
+| `/ws/providers/<page>/panels/<panel>` | 面板流。 |
+
+## 服务端
+
+`WebApp` 默认监听 `127.0.0.1`，支持由依赖配置指定监听地址。从首选端口起最多尝试五个端口；
+端口为 0 时仅申请一次系统分配。WebSocket 使用 `noServer` 分派 `/ws/debug`、`/ws/sessions` 和面板流。
+所有请求与 upgrade 先校验 Host 头：只接受回环名或显式绑定的地址，绑到通配地址时不校验。
+写请求与 upgrade 再按 Host 校验 Origin，拒绝不匹配或无效的 Origin；缺少 Origin 时放行。
+
+`/assets` 提供 `dist/web` 资源。首页在最后一个 `</body>` 前注入带 hash 的入口。
+扩展面板通过 `/assets/extensions/<包>/<版本>/<文件>` 提供，仅允许 manifest 声明的脚本与样式文件。
+
+`createBot()` 通过 `WebAppDeps` 注入事件库、session、运行控制、配置、存储、`consolePageSources` 和扩展信息。
+调试流以 `head` 提供本次 `Persona.sessionHead()` 的合成开头；它不属于持久 session。
+`providersLamp` 汇总本地端点可用性，由状态灯接口提供给浏览器。
+
+## 浏览器
+
+`llm-settings` 从端点状态中的 ConfigGroup 渲染连接字段与声明的请求路径,使用 `ctx.setConfig` 保存。
+
+`main.ts` 的 `FEATURES` 包含 `live`、`core`、`usage`、`provider`、`world`、`extensions`、`prompts`、
+`appearance`、`settings`。贡献页由 manifest 加载，保留路由段 `provider` 交由 `ConsolePageHost` 处理。
+`features/config/view.ts` 与 `features/storage/view.ts` 是配置组与存储清单的通用视图,运行诊断页与
+`ConsolePageHost` 共用。
+
+`ConsolePageHost` 渲染页面声明中的徽标、状态灯、配置组、提示词文档、存储项与面板。
+`ConsolePageLoader` 按页 id 查找 bundle，缓存成功的导入，校验默认导出的 `{ panels }`；缺少 `mount` 的面板显示错误。
+卸载依次执行 abort、dispose、清空 root，并释放上下文登记的轮询、RAF、observer、监听器、请求和音频资源。
+
+`ConsoleUi` 返回 DOM 节点，文本参数不作为 HTML 解析。面板通过 `signal` 管理资源。abort 会关闭关联的 toast、confirm 和 drawer，
+待决 confirm 返回 `false`。
+
+## 构建
+
+`scripts/build-web.ts` 使用以下入口：
+
+| 入口 | 资源键 |
+|---|---|
+| `src/web/client/main.ts` | 控制台主入口。 |
+| `src/worlds/*/console/client.ts` | `world:<name>` |
+| `src/providers/*/console/client.ts` | `llm:<name>` |
+| `bots/*/console/client.ts` | `persona:<name>` |
+
+esbuild 输出分包 ESM 和带 hash 的文件名，写入 `asset-manifest.json`；Tailwind 输出 `styles.css`。
+浏览器代码使用 `tsconfig.web.json` 检查：`pnpm typecheck:web`。