@sogni-ai/sogni-client 4.2.0-alpha.21 → 4.2.0-alpha.22

package/src/Chat/hostedToolValidation.generated.ts

@@ -0,0 +1,453 @@
+/* eslint-disable */
+// Generated by scripts/sync-hosted-tool-validation.mjs.
+// Source: @sogni/creative-agent/src/backbone/reference/toolValidation.ts
+// Do not edit by hand. Run `npm run sync:hosted-tool-validation` to refresh.
+export interface HostedToolSchemaProperty {
+  type?: string | string[];
+  const?: unknown;
+  enum?: unknown[];
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number | boolean;
+  exclusiveMaximum?: number | boolean;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  minItems?: number;
+  maxItems?: number;
+  items?: HostedToolSchemaProperty | HostedToolSchemaProperty[];
+  required?: string[];
+  properties?: Record<string, HostedToolSchemaProperty>;
+  additionalProperties?: boolean | HostedToolSchemaProperty;
+  anyOf?: HostedToolSchemaProperty[];
+  oneOf?: HostedToolSchemaProperty[];
+  allOf?: HostedToolSchemaProperty[];
+}
+
+export interface HostedToolSchema extends HostedToolSchemaProperty {
+  type?: string | string[];
+}
+
+export interface HostedToolDefinition {
+  function: {
+    name: string;
+    parameters?: HostedToolSchema;
+  };
+}
+
+export interface ValidateHostedToolArgumentsOptions {
+  skipEnumProperties?: string[];
+  coercePrimitives?: boolean;
+  stripUnknownProperties?: boolean;
+}
+
+export interface HostedToolArgumentValidationResult {
+  ok: boolean;
+  errors: string[];
+}
+
+export interface NormalizeHostedToolArgumentsResult extends HostedToolArgumentValidationResult {
+  cleaned: Record<string, unknown>;
+  warnings: string[];
+}
+
+function matchesType(value: unknown, type: string): boolean {
+  switch (type) {
+    case 'array':
+      return Array.isArray(value);
+    case 'integer':
+      return typeof value === 'number' && Number.isInteger(value);
+    case 'number':
+      return typeof value === 'number' && Number.isFinite(value);
+    case 'boolean':
+      return typeof value === 'boolean';
+    case 'object':
+      return typeof value === 'object' && value !== null && !Array.isArray(value);
+    case 'string':
+      return typeof value === 'string';
+    case 'null':
+      return value === null;
+    default:
+      return true;
+  }
+}
+
+function typeLabel(type: string | string[] | undefined): string {
+  if (Array.isArray(type)) return type.join(' or ');
+  return type ?? 'valid value';
+}
+
+function typeList(type: string | string[] | undefined): string[] {
+  if (!type) return [];
+  return Array.isArray(type) ? type : [type];
+}
+
+function formatEnum(values: unknown[]): string {
+  return values.map(value => JSON.stringify(value)).join(', ');
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function valuesEqual(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true;
+  if (typeof left !== typeof right) return false;
+  if (left === null || right === null) return left === right;
+  if (typeof left !== 'object') return false;
+  try {
+    return JSON.stringify(left) === JSON.stringify(right);
+  } catch {
+    return false;
+  }
+}
+
+function coerceValueForTypes(
+  value: unknown,
+  allowedTypes: string[],
+): { value: unknown; coerced: boolean } {
+  if (typeof value !== 'string') return { value, coerced: false };
+  const trimmed = value.trim();
+  if (!trimmed) return { value, coerced: false };
+
+  if (allowedTypes.includes('integer') || allowedTypes.includes('number')) {
+    const numberValue = Number(trimmed);
+    if (
+      Number.isFinite(numberValue)
+      && (!allowedTypes.includes('integer') || Number.isInteger(numberValue))
+    ) {
+      return { value: numberValue, coerced: true };
+    }
+  }
+
+  if (allowedTypes.includes('boolean')) {
+    if (/^(?:true|false)$/i.test(trimmed)) {
+      return { value: trimmed.toLowerCase() === 'true', coerced: true };
+    }
+  }
+
+  return { value, coerced: false };
+}
+
+interface SchemaValidationContext {
+  skipEnumProperties: Set<string>;
+  coercePrimitives: boolean;
+  stripUnknownProperties: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+function validateNumberBounds(
+  path: string,
+  value: number,
+  schema: HostedToolSchemaProperty,
+  errors: string[],
+): void {
+  if (schema.minimum !== undefined && value < schema.minimum) {
+    errors.push(`Argument "${path}" must be at least ${schema.minimum}`);
+  }
+  if (schema.maximum !== undefined && value > schema.maximum) {
+    errors.push(`Argument "${path}" must be at most ${schema.maximum}`);
+  }
+  if (typeof schema.exclusiveMinimum === 'number' && value <= schema.exclusiveMinimum) {
+    errors.push(`Argument "${path}" must be greater than ${schema.exclusiveMinimum}`);
+  }
+  if (typeof schema.exclusiveMaximum === 'number' && value >= schema.exclusiveMaximum) {
+    errors.push(`Argument "${path}" must be less than ${schema.exclusiveMaximum}`);
+  }
+  if (schema.exclusiveMinimum === true && schema.minimum !== undefined && value <= schema.minimum) {
+    errors.push(`Argument "${path}" must be greater than ${schema.minimum}`);
+  }
+  if (schema.exclusiveMaximum === true && schema.maximum !== undefined && value >= schema.maximum) {
+    errors.push(`Argument "${path}" must be less than ${schema.maximum}`);
+  }
+}
+
+function validateStringConstraints(
+  path: string,
+  value: string,
+  schema: HostedToolSchemaProperty,
+  errors: string[],
+): void {
+  if (schema.minLength !== undefined && value.length < schema.minLength) {
+    errors.push(`Argument "${path}" must contain at least ${schema.minLength} character${schema.minLength === 1 ? '' : 's'}`);
+  }
+  if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+    errors.push(`Argument "${path}" must contain at most ${schema.maxLength} character${schema.maxLength === 1 ? '' : 's'}`);
+  }
+  if (schema.pattern) {
+    try {
+      // Hosted-tool schema authors near-universally assume anchored matching
+      // for ID-like fields, but JSON Schema `pattern` is unanchored. Auto-anchor
+      // to prevent prefix/suffix injection (e.g. `pattern: 'safe-prefix-'` should
+      // reject `'evil-safe-prefix-suffix'`). Wrapping with `^(?:...)$` is safe
+      // even for already-anchored patterns — `^^…$$` still matches the same set.
+      if (!new RegExp(`^(?:${schema.pattern})$`).test(value)) {
+        errors.push(`Argument "${path}" must match pattern ${JSON.stringify(schema.pattern)}`);
+      }
+    } catch {
+      errors.push(`Schema for "${path}" contains invalid pattern ${JSON.stringify(schema.pattern)}`);
+    }
+  }
+}
+
+function validateCompositeSchema(
+  path: string,
+  value: unknown,
+  schema: HostedToolSchemaProperty,
+  context: SchemaValidationContext,
+): { matched: boolean; value: unknown } {
+  if (schema.allOf) {
+    let nextValue = value;
+    for (const childSchema of schema.allOf) {
+      const result = validateValueAgainstSchema(path, nextValue, childSchema, context);
+      nextValue = result.value;
+    }
+    return { matched: true, value: nextValue };
+  }
+
+  const alternatives = schema.oneOf ?? schema.anyOf;
+  if (!alternatives) return { matched: true, value };
+
+  const matches: unknown[] = [];
+  for (const childSchema of alternatives) {
+    const trial: SchemaValidationContext = {
+      ...context,
+      errors: [],
+      warnings: [],
+    };
+    const result = validateValueAgainstSchema(path, value, childSchema, trial);
+    if (trial.errors.length === 0) matches.push(result.value);
+  }
+
+  if (schema.oneOf && matches.length !== 1) {
+    context.errors.push(`Argument "${path}" must match exactly one allowed schema`);
+    return { matched: false, value };
+  }
+  if (schema.anyOf && matches.length < 1) {
+    context.errors.push(`Argument "${path}" must match at least one allowed schema`);
+    return { matched: false, value };
+  }
+
+  return { matched: true, value: matches[0] ?? value };
+}
+
+function validateObjectAgainstSchema(
+  path: string,
+  value: Record<string, unknown>,
+  schema: HostedToolSchemaProperty,
+  context: SchemaValidationContext,
+): Record<string, unknown> {
+  const properties = schema.properties ?? {};
+  const cleaned: Record<string, unknown> = {};
+
+  for (const required of schema.required ?? []) {
+    const propValue = value[required];
+    // Empty string and empty array are treated as missing — schema authors
+    // assume `required` means "has a usable value", not "is non-undefined".
+    // Empty object is left untouched (some schemas legitimately accept `{}`).
+    const isMissing =
+      propValue === undefined
+      || propValue === null
+      || propValue === ''
+      || (Array.isArray(propValue) && propValue.length === 0);
+    if (isMissing) {
+      context.errors.push(`Missing required argument "${path ? `${path}.` : ''}${required}"`);
+    }
+  }
+
+  for (const [name, entryValue] of Object.entries(value)) {
+    if (entryValue === undefined || entryValue === null) {
+      if (name in properties || !context.stripUnknownProperties) cleaned[name] = entryValue;
+      continue;
+    }
+
+    const property = properties[name];
+    if (!property) {
+      if (schema.additionalProperties === false || context.stripUnknownProperties) {
+        context.warnings.push(`Stripped unknown argument "${path ? `${path}.` : ''}${name}"`);
+      } else if (isRecord(schema.additionalProperties)) {
+        cleaned[name] = validateValueAgainstSchema(
+          path ? `${path}.${name}` : name,
+          entryValue,
+          schema.additionalProperties,
+          context,
+        ).value;
+      } else {
+        cleaned[name] = entryValue;
+      }
+      continue;
+    }
+
+    cleaned[name] = validateValueAgainstSchema(
+      path ? `${path}.${name}` : name,
+      entryValue,
+      property,
+      context,
+    ).value;
+  }
+
+  return cleaned;
+}
+
+function validateArrayAgainstSchema(
+  path: string,
+  value: unknown[],
+  schema: HostedToolSchemaProperty,
+  context: SchemaValidationContext,
+): unknown[] {
+  if (schema.minItems !== undefined && value.length < schema.minItems) {
+    context.errors.push(`Argument "${path}" must contain at least ${schema.minItems} item${schema.minItems === 1 ? '' : 's'}`);
+  }
+  if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+    context.errors.push(`Argument "${path}" must contain at most ${schema.maxItems} item${schema.maxItems === 1 ? '' : 's'}`);
+  }
+
+  if (!schema.items) return value;
+
+  if (Array.isArray(schema.items)) {
+    const tupleSchemas = schema.items;
+    return value.map((item, index) => {
+      const itemSchema = tupleSchemas[index];
+      return itemSchema
+        ? validateValueAgainstSchema(`${path}[${index}]`, item, itemSchema, context).value
+        : item;
+    });
+  }
+
+  return value.map((item, index) => validateValueAgainstSchema(`${path}[${index}]`, item, schema.items as HostedToolSchemaProperty, context).value);
+}
+
+function validateValueAgainstSchema(
+  path: string,
+  rawValue: unknown,
+  schema: HostedToolSchemaProperty,
+  context: SchemaValidationContext,
+): { value: unknown } {
+  const composite = validateCompositeSchema(path, rawValue, schema, context);
+  if (!composite.matched) return { value: rawValue };
+  let value = composite.value;
+
+  const allowedTypes = typeList(schema.type);
+  if (
+    context.coercePrimitives
+    && allowedTypes.length > 0
+    && !allowedTypes.some(type => matchesType(value, type))
+  ) {
+    const coerced = coerceValueForTypes(value, allowedTypes);
+    if (coerced.coerced) {
+      context.warnings.push(`Coerced argument "${path}" to ${typeof coerced.value}`);
+      value = coerced.value;
+    }
+  }
+
+  if (allowedTypes.length > 0 && !allowedTypes.some(type => matchesType(value, type))) {
+    context.errors.push(`Argument "${path}" must be ${typeLabel(schema.type)}`);
+    return { value };
+  }
+
+  if (schema.const !== undefined && !valuesEqual(value, schema.const)) {
+    context.errors.push(`Argument "${path}" must be ${JSON.stringify(schema.const)}`);
+  }
+
+  if (
+    schema.enum
+    && !context.skipEnumProperties.has(path)
+    && !context.skipEnumProperties.has(path.split('.').at(-1) ?? path)
+    && !schema.enum.some(candidate => valuesEqual(candidate, value))
+  ) {
+    context.errors.push(`Argument "${path}" must be one of ${formatEnum(schema.enum)}`);
+  }
+
+  if (typeof value === 'number') {
+    validateNumberBounds(path, value, schema, context.errors);
+  }
+  if (typeof value === 'string') {
+    validateStringConstraints(path, value, schema, context.errors);
+  }
+  if (Array.isArray(value)) {
+    value = validateArrayAgainstSchema(path, value, schema, context);
+  }
+  if (isRecord(value)) {
+    value = validateObjectAgainstSchema(path, value, schema, context);
+  }
+
+  return { value };
+}
+
+export function validateAndNormalizeHostedToolArguments(
+  tools: HostedToolDefinition[],
+  toolName: string,
+  args: Record<string, unknown>,
+  options: ValidateHostedToolArgumentsOptions = {},
+): NormalizeHostedToolArgumentsResult {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return {
+      ok: false,
+      errors: ['Tool arguments must be a JSON object'],
+      cleaned: {},
+      warnings: [],
+    };
+  }
+
+  const tool = tools.find(candidate => candidate.function.name === toolName);
+  if (!tool) {
+    return {
+      ok: false,
+      errors: [`Unknown hosted Sogni tool "${toolName}"`],
+      cleaned: args,
+      warnings: [],
+    };
+  }
+
+  const schema = tool.function.parameters;
+  if (!schema) {
+    return { ok: true, errors: [], cleaned: args, warnings: [] };
+  }
+
+  const context: SchemaValidationContext = {
+    skipEnumProperties: new Set(options.skipEnumProperties ?? ['model']),
+    coercePrimitives: options.coercePrimitives === true,
+    stripUnknownProperties: options.stripUnknownProperties === true,
+    errors: [],
+    warnings: [],
+  };
+
+  const normalizedSchema: HostedToolSchema = {
+    ...schema,
+    type: schema.type ?? 'object',
+  };
+  const cleaned = validateValueAgainstSchema('', args, normalizedSchema, context).value;
+
+  return {
+    ok: context.errors.length === 0,
+    errors: context.errors,
+    cleaned: isRecord(cleaned) ? cleaned : args,
+    warnings: context.warnings,
+  };
+}
+
+export function validateHostedToolArguments(
+  tools: HostedToolDefinition[],
+  toolName: string,
+  args: Record<string, unknown>,
+  options: ValidateHostedToolArgumentsOptions = {},
+): HostedToolArgumentValidationResult {
+  const result = validateAndNormalizeHostedToolArguments(tools, toolName, args, options);
+  return {
+    ok: result.ok,
+    errors: result.errors,
+  };
+}
+
+export function assertHostedToolArguments(
+  tools: HostedToolDefinition[],
+  toolName: string,
+  args: Record<string, unknown>,
+  options?: ValidateHostedToolArgumentsOptions,
+): void {
+  const result = validateHostedToolArguments(tools, toolName, args, options);
+  if (!result.ok) {
+    throw new Error(`Invalid ${toolName} arguments: ${result.errors.join('; ')}`);
+  }
+}

package/src/Chat/index.ts

@@ -14,11 +14,15 @@ import {
   ChatJobStateEvent,
   ChatRequestMessage,
   ChatMessage,
+  ChatRunEvent,
+  ChatRunRecord,
   HostedChatCompletionParams,
   HostedChatCompletionResult,
   LLMCostEstimation,
   LLMEstimateResponse,
   LLMModelInfo,
+  StartChatRunParams,
+  StreamChatRunEventsOptions,
   ToolCall,
   ToolHistoryEntry
 } from './types';
@@ -136,10 +140,37 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
       ((params: ChatCompletionParams) => Promise<ChatStream | ChatCompletionResult>);
   };
 
+  /**
+   * Hosted REST chat completion (`POST /v1/chat/completions`). The API
+   * executes any eligible hosted tools server-side and returns the
+   * final result within the request lifetime.
+   */
   hosted: {
     create: (params: HostedChatCompletionParams) => Promise<HostedChatCompletionResult>;
   };
 
+  /**
+   * Durable hosted chat runs (`POST /v1/chat/runs`). A run is submitted
+   * and persisted server-side; the executor drives the LLM/tool loop
+   * without requiring the client to stay connected. Clients can
+   * disconnect and reattach via SSE `Last-Event-ID` replay or fetch
+   * the final snapshot.
+   *
+   * - `create` returns the persisted run record immediately (202).
+   * - `get` reads the current run state.
+   * - `cancel` flips the run to `cancelled` and aborts in-flight work.
+   * - `streamEvents` yields `ChatRunEvent`s via SSE.
+   */
+  runs: {
+    create: (params: StartChatRunParams) => Promise<ChatRunRecord>;
+    get: (runId: string) => Promise<ChatRunRecord>;
+    cancel: (runId: string, reason?: string) => Promise<ChatRunRecord>;
+    streamEvents: (
+      runId: string,
+      options?: StreamChatRunEventsOptions
+    ) => AsyncIterableIterator<ChatRunEvent>;
+  };
+
   constructor(config: ApiConfig, projects?: ProjectsApi) {
     super(config);
 
@@ -157,6 +188,12 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
     this.hosted = {
       create: this.createHostedCompletion.bind(this)
     };
+    this.runs = {
+      create: this.createChatRun.bind(this),
+      get: this.getChatRun.bind(this),
+      cancel: this.cancelChatRun.bind(this),
+      streamEvents: this.streamChatRunEvents.bind(this)
+    };
 
     // Set up the tools API (requires ProjectsApi for media generation).
     // When ProjectsApi is not provided, tool execution methods will throw at runtime.
@@ -364,7 +401,7 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
       {
         model: params.model,
         messages: normalizedMessages,
-        app_source: params.app_source || params.appSource || this.client.appSource,
+        app_source: params.app_source ?? params.appSource ?? this.client.appSource,
         max_tokens: params.max_tokens,
         temperature: params.temperature,
         top_p: params.top_p,
@@ -374,12 +411,12 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
         frequency_penalty: params.frequency_penalty,
         presence_penalty: params.presence_penalty,
         stop: params.stop,
-        token_type: params.token_type || params.tokenType,
+        token_type: params.token_type ?? params.tokenType,
         tools: params.tools,
         tool_choice: params.tool_choice,
         sogni_tools: this.normalizeSogniToolsMode(params.sogni_tools),
         sogni_tool_execution: params.sogni_tool_execution,
-        task_profile: params.taskProfile,
+        task_profile: params.task_profile ?? params.taskProfile,
         media_references: params.media_references ?? params.mediaReferences,
         api_media_references: params.api_media_references ?? params.apiMediaReferences,
         ...(chatTemplateKwargs && { chat_template_kwargs: chatTemplateKwargs }),
@@ -389,6 +426,164 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
     );
   }
 
+  private async chatRunFetch(path: string, options: RequestInit = {}): Promise<Response> {
+    const url = new URL(path, this.client.rest.baseUrl).toString();
+    const authenticated = await this.client.auth.authenticateRequest(options);
+    return fetch(url, authenticated);
+  }
+
+  private async chatRunJson<T>(path: string, options: RequestInit = {}): Promise<T> {
+    const response = await this.chatRunFetch(path, options);
+    if (!response.ok) {
+      const text = await response.text();
+      let payload: Record<string, unknown> | undefined;
+      try {
+        payload = text ? (JSON.parse(text) as Record<string, unknown>) : undefined;
+      } catch {
+        payload = { message: text };
+      }
+      const message =
+        (payload && typeof payload.message === 'string' && payload.message) ||
+        response.statusText ||
+        `Chat run request failed with status ${response.status}`;
+      const err = new Error(message);
+      (err as { status?: number }).status = response.status;
+      throw err;
+    }
+    return (await response.json()) as T;
+  }
+
+  /**
+   * Submit a durable hosted chat run. Returns the persisted run record;
+   * the executor drives the LLM/tool loop server-side.
+   */
+  private async createChatRun(params: StartChatRunParams): Promise<ChatRunRecord> {
+    const body: Record<string, unknown> = {
+      messages: params.messages,
+      ...(params.tools ? { tools: params.tools } : {}),
+      ...(params.toolChoice !== undefined ? { tool_choice: params.toolChoice } : {}),
+      ...(params.model ? { model: params.model } : {}),
+      ...(params.sampling ? { sampling: params.sampling } : {}),
+      ...(params.mediaReferences ? { media_references: params.mediaReferences } : {}),
+      ...(params.mediaContext ? { media_context: params.mediaContext } : {}),
+      ...(params.maxEstimatedCapacityUnits !== undefined
+        ? { max_estimated_capacity_units: params.maxEstimatedCapacityUnits }
+        : {}),
+      ...(params.confirmCost !== undefined ? { confirm_cost: params.confirmCost } : {}),
+      ...(params.sessionId ? { session_id: params.sessionId } : {}),
+      ...(params.clientMessageId ? { client_message_id: params.clientMessageId } : {}),
+      ...(params.tokenType ? { token_type: params.tokenType } : {}),
+      ...(params.appSource ? { app_source: params.appSource } : {})
+    };
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (params.idempotencyKey) headers['Idempotency-Key'] = params.idempotencyKey;
+    const response = await this.chatRunJson<{
+      status: string;
+      data: { run: ChatRunRecord; idempotent?: boolean };
+    }>('/v1/chat/runs', {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body)
+    });
+    return response.data.run;
+  }
+
+  /** Read a persisted chat run record. */
+  private async getChatRun(runId: string): Promise<ChatRunRecord> {
+    const response = await this.chatRunJson<{ status: string; data: { run: ChatRunRecord } }>(
+      `/v1/chat/runs/${encodeURIComponent(runId)}`
+    );
+    return response.data.run;
+  }
+
+  /** Cancel an in-flight chat run. */
+  private async cancelChatRun(runId: string, reason?: string): Promise<ChatRunRecord> {
+    const response = await this.chatRunJson<{ status: string; data: { run: ChatRunRecord } }>(
+      `/v1/chat/runs/${encodeURIComponent(runId)}/cancel`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(reason ? { reason } : {})
+      }
+    );
+    return response.data.run;
+  }
+
+  /**
+   * SSE iterator over chat-run events. Honors `Last-Event-ID` for replay.
+   * Yields events as `ChatRunEvent`. Caller is responsible for breaking
+   * the loop when they see a terminal `run_*` event type they care about.
+   */
+  private async *streamChatRunEvents(
+    runId: string,
+    options: StreamChatRunEventsOptions = {}
+  ): AsyncIterableIterator<ChatRunEvent> {
+    const headers: Record<string, string> = { Accept: 'text/event-stream' };
+    if (options.lastEventId !== undefined && Number.isFinite(options.lastEventId)) {
+      headers['Last-Event-ID'] = String(options.lastEventId);
+    }
+    const response = await this.chatRunFetch(
+      `/v1/chat/runs/${encodeURIComponent(runId)}/events/stream`,
+      { headers, signal: options.signal }
+    );
+    if (!response.ok || !response.body) {
+      throw new Error(`Chat run event stream failed with status ${response.status}`);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    const findFrameBoundary = (source: string): { index: number; length: number } | null => {
+      const lf = source.indexOf('\n\n');
+      const crlf = source.indexOf('\r\n\r\n');
+      if (lf === -1 && crlf === -1) return null;
+      if (lf === -1) return { index: crlf, length: 4 };
+      if (crlf === -1 || lf < crlf) return { index: lf, length: 2 };
+      return { index: crlf, length: 4 };
+    };
+
+    const yieldFrame = (frame: string): ChatRunEvent | null => {
+      if (!frame.trim() || frame.startsWith(':')) return null;
+      let eventName = 'message';
+      let data = '';
+      for (const rawLine of frame.split(/\r?\n/)) {
+        if (rawLine.startsWith('event:')) eventName = rawLine.slice(6).trim();
+        else if (rawLine.startsWith('data:')) data += (data ? '\n' : '') + rawLine.slice(5).trim();
+      }
+      if (eventName === 'run_status' || !data) return null;
+      try {
+        return JSON.parse(data) as ChatRunEvent;
+      } catch {
+        return null;
+      }
+    };
+
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) {
+          const remaining = buffer.trim();
+          if (remaining) {
+            const parsed = yieldFrame(remaining);
+            if (parsed) yield parsed;
+          }
+          return;
+        }
+        buffer += decoder.decode(value, { stream: true });
+        let boundary = findFrameBoundary(buffer);
+        while (boundary !== null) {
+          const frame = buffer.slice(0, boundary.index);
+          buffer = buffer.slice(boundary.index + boundary.length);
+          boundary = findFrameBoundary(buffer);
+          const parsed = yieldFrame(frame);
+          if (parsed) yield parsed;
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
   /**
    * Send a single chat completion request (no auto tool execution).
    */