feat(sdk/js): add responses FFI fallback

Use the existing chat_completions native command for Responses create and streaming calls when a CoreInterop transport is available, with HTTP fallback for server-backed operations. Keep FFI-created stored responses available through the same client instance and cover the behavior with unit tests.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: MaanavD

sdk/js/README.md

@@ -252,11 +252,12 @@ for await (const chunk of audioClient.transcribeStreaming('/path/to/audio.wav'))
 
 ### Responses API
 
-Use the Responses API client for OpenAI-compatible text, tool, streaming, stored-response, and vision workflows over the embedded web service:
+Use the Responses API client for OpenAI-compatible text, tool, streaming, stored-response, and vision workflows. Clients created from `FoundryLocalManager` or a model use native FFI for `create()` and `createStreaming()` when possible, with HTTP fallback when a web service URL is available.
 
 ```typescript
 import { createImageContentFromFile, getOutputText } from 'foundry-local-sdk';
 
+// Optional: start the web service for HTTP fallback and server-backed list/get/delete/cancel operations.
 manager.startWebService();
 
 const client = manager.createResponsesClient(model.id);
@@ -285,7 +286,7 @@ const visionResponse = await client.create([
 console.log(getOutputText(visionResponse));
 ```
 
-Vision helpers support `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, and `.bmp` files. `createImageContentFromFile()` sends Foundry Local's server contract (`image_data` plus `media_type`); `createImageContentFromUrl()` sends `image_url` and lets the server infer the media type.
+Vision helpers support `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, and `.bmp` files. `createImageContentFromFile()` sends Foundry Local's `image_data` plus `media_type` contract; the FFI path converts that to the chat-completions data URL shape internally. `createImageContentFromUrl()` sends `image_url` and lets the runtime infer the media type.
 
 ### Embedded Web Service
 

sdk/js/src/detail/model.ts

@@ -196,10 +196,11 @@ export class Model implements IModel {
 
     /**
      * Creates a ResponsesClient for interacting with the model via the Responses API.
-     * @param baseUrl - The base URL of the Foundry Local web service.
+     * Uses native FFI for create/createStreaming and falls back to HTTP when baseUrl is provided.
+     * @param baseUrl - Optional base URL of the Foundry Local web service for HTTP fallback and server-backed operations.
      * @returns A ResponsesClient instance.
      */
-    public createResponsesClient(baseUrl: string): ResponsesClient {
+    public createResponsesClient(baseUrl?: string): ResponsesClient {
         return this.selectedVariant.createResponsesClient(baseUrl);
     }
-}
+}

sdk/js/src/detail/modelVariant.ts

@@ -189,10 +189,11 @@ export class ModelVariant implements IModel {
 
     /**
      * Creates a ResponsesClient for interacting with the model via the Responses API.
-     * @param baseUrl - The base URL of the Foundry Local web service.
+     * Uses native FFI for create/createStreaming and falls back to HTTP when baseUrl is provided.
+     * @param baseUrl - Optional base URL of the Foundry Local web service for HTTP fallback and server-backed operations.
      * @returns A ResponsesClient instance.
      */
-    public createResponsesClient(baseUrl: string): ResponsesClient {
-        return new ResponsesClient(baseUrl, this._modelInfo.id);
+    public createResponsesClient(baseUrl?: string): ResponsesClient {
+        return ResponsesClient.createWithCoreInterop(baseUrl, this._modelInfo.id, this.coreInterop);
     }
 }

sdk/js/src/foundryLocalManager.ts

@@ -214,17 +214,12 @@ export class FoundryLocalManager {
 
     /**
      * Creates a ResponsesClient for interacting with the Responses API.
-     * The web service must be started first via `startWebService()`.
+     * Uses native FFI for create/createStreaming and falls back to HTTP if the web
+     * service has been started via `startWebService()`.
      * @param modelId - Optional default model ID for requests.
      * @returns A ResponsesClient instance.
-     * @throws Error - If the web service is not running.
      */
     public createResponsesClient(modelId?: string): ResponsesClient {
-        if (this._urls.length === 0) {
-            throw new Error(
-                'Web service is not running. Call startWebService() before creating a ResponsesClient.'
-            );
-        }
-        return new ResponsesClient(this._urls[0], modelId);
+        return ResponsesClient.createWithCoreInterop(this._urls[0], modelId, this.coreInterop);
     }
 }

sdk/js/src/imodel.ts

@@ -36,11 +36,10 @@ export interface IModel {
     createLiveTranscriptionSession(): LiveAudioTranscriptionSession;
     /**
      * Creates a ResponsesClient for interacting with the model via the Responses API.
-     * Unlike createChatClient/createAudioClient (which use FFI), the Responses API
-     * is HTTP-based, so the web service base URL must be provided.
-     * @param baseUrl - The base URL of the Foundry Local web service.
+     * Uses native FFI for create/createStreaming and falls back to HTTP when baseUrl is provided.
+     * @param baseUrl - Optional base URL of the Foundry Local web service for HTTP fallback and server-backed operations.
      */
-    createResponsesClient(baseUrl: string): ResponsesClient;
+    createResponsesClient(baseUrl?: string): ResponsesClient;
 
     /**
      * Variants of the model that are available. Variants of the model are optimized for different devices.