test(samples/js): add Responses web service sample and integration coverage

sdk/js/examples/responses.ts

@@ -3,8 +3,9 @@
 // Licensed under the MIT License.
 // -------------------------------------------------------------------------
 
-import { FoundryLocalManager, getOutputText } from '../src/index.js';
-import type { StreamingEvent, FunctionToolDefinition, FunctionCallItem } from '../src/types.js';
+import * as fs from 'fs';
+import { FoundryLocalManager, getOutputText, createImageContentFromFile } from '../src/index.js';
+import type { StreamingEvent, FunctionToolDefinition, FunctionCallItem, MessageItem } from '../src/types.js';
 
 async function main() {
     try {
@@ -121,6 +122,35 @@ async function main() {
         const deleted = await client.delete(stored.id);
         console.log(`Deleted: ${deleted.deleted}`);
 
+        // =================================================================
+        // Example 6: List all stored responses
+        // =================================================================
+        console.log('\n--- Example 6: List stored responses ---');
+        const allResponses = await client.list();
+        console.log(`Listed ${allResponses.data.length} stored responses`);
+
+        // =================================================================
+        // Example 7: Vision — describe an image
+        // =================================================================
+        console.log('\n--- Example 7: Vision ---');
+        const testImagePath = 'path/to/test-image.png'; // Replace with a real image path
+        if (fs.existsSync(testImagePath)) {
+            const imageContent = await createImageContentFromFile(testImagePath);
+            const visionResponse = await client.create([
+                {
+                    type: 'message',
+                    role: 'user',
+                    content: [
+                        { type: 'input_text', text: 'Describe this image in one sentence.' },
+                        imageContent,
+                    ],
+                } as MessageItem,
+            ]);
+            console.log(`Vision: ${getOutputText(visionResponse)}`);
+        } else {
+            console.log('(Skipped: test image not found)');
+        }
+
         // Cleanup
         manager.stopWebService();
         await model.unload();

sdk/js/src/index.ts

@@ -12,6 +12,7 @@ export { EmbeddingClient } from './openai/embeddingClient.js';
 export { LiveAudioTranscriptionSession, LiveAudioTranscriptionOptions } from './openai/liveAudioTranscriptionClient.js';
 export type { LiveAudioTranscriptionResponse, TranscriptionContentPart } from './openai/liveAudioTranscriptionTypes.js';
 export { ResponsesClient, ResponsesClientSettings, getOutputText } from './openai/responsesClient.js';
+export { createImageContentFromFile, createImageContentFromUrl } from './openai/vision.js';
 export { ModelLoadManager } from './detail/modelLoadManager.js';
 /** @internal */
 export { CoreInterop } from './detail/coreInterop.js';

sdk/js/src/openai/responsesClient.ts

@@ -9,6 +9,7 @@ import {
     StreamingEvent,
     InputItemsListResponse,
     DeleteResponseResult,
+    ListResponsesResult,
     ResponseInputItem,
     MessageItem,
     ContentPart,
@@ -52,6 +53,11 @@ export class ResponsesClientSettings {
     toolChoice?: ResponseToolChoice;
     truncation?: TruncationStrategy;
     parallelToolCalls?: boolean;
+    /**
+     * Whether to store the response server-side so it can be retrieved via `get()`, `list()`,
+     * `getInputItems()`, or referenced by `previous_response_id`. Defaults to `true` when not
+     * explicitly set. Set to `false` to disable persistence for a given client.
+     */
     store?: boolean;
     metadata?: Record<string, string>;
     reasoning?: ReasoningConfig;
@@ -76,7 +82,8 @@ export class ResponsesClientSettings {
             tool_choice: this.toolChoice,
             truncation: this.truncation,
             parallel_tool_calls: this.parallelToolCalls,
-            store: this.store,
+            // Default store to true when not explicitly set
+            store: this.store !== undefined ? this.store : true,
             metadata: this.metadata,
             reasoning: this.reasoning ? filterUndefined(this.reasoning) : undefined,
             text: this.text ? filterUndefined(this.text) : undefined,
@@ -275,6 +282,14 @@ export class ResponsesClient {
         );
     }
 
+    /**
+     * Lists all stored responses.
+     * @returns The list of Response objects.
+     */
+    public async list(): Promise<ListResponsesResult> {
+        return this.fetchJson<ListResponsesResult>('/v1/responses', { method: 'GET' });
+    }
+
     // ========================================================================
     // Internal helpers
     // ========================================================================

sdk/js/src/openai/vision.ts

@@ -0,0 +1,158 @@
+// -------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+// -------------------------------------------------------------------------
+
+import * as path from 'path';
+import { promises as fsPromises } from 'fs';
+import type { InputImageContent } from '../types.js';
+
+const MEDIA_TYPE_MAP: Record<string, string> = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.bmp': 'image/bmp',
+};
+
+/**
+ * Options for `createImageContentFromFile`.
+ */
+export interface ImageContentOptions {
+    /** Detail level hint for the model. */
+    detail?: 'low' | 'high' | 'auto';
+    /**
+     * If set, the longest dimension of the image will be scaled down to this value
+     * (preserving aspect ratio) before encoding. Must be a finite positive integer.
+     * Requires the `sharp` package to be installed as an optional peer dependency
+     * (`npm install sharp`). If `sharp` is not available, a warning is printed and
+     * the original image is used unresized.
+     */
+    maxDimension?: number;
+}
+
+/**
+ * Creates an `InputImageContent` part by reading an image file from disk.
+ * The file is base64-encoded and embedded directly in the content part.
+ *
+ * The second argument accepts either an `ImageContentOptions` object or a shorthand
+ * detail string (`'low' | 'high' | 'auto'`) for convenience.
+ *
+ * @param filePath - Absolute or relative path to the image file.
+ * @param options - Optional `ImageContentOptions`, or a shorthand detail string.
+ * @returns A `Promise<InputImageContent>` with base64-encoded image data.
+ * @throws If the file does not exist, the extension is unsupported, or `maxDimension`
+ *         is not a finite positive integer.
+ */
+export async function createImageContentFromFile(
+    filePath: string,
+    options?: ImageContentOptions | 'low' | 'high' | 'auto'
+): Promise<InputImageContent> {
+    // Support the shorthand signature: createImageContentFromFile(path, detail?)
+    const opts: ImageContentOptions = typeof options === 'string'
+        ? { detail: options }
+        : (options ?? {});
+
+    if (opts.maxDimension !== undefined) {
+        if (!Number.isFinite(opts.maxDimension) || !Number.isInteger(opts.maxDimension) || opts.maxDimension <= 0) {
+            throw new Error(`Invalid maxDimension: ${opts.maxDimension}. Expected a finite positive integer.`);
+        }
+    }
+
+    const ext = path.extname(filePath).toLowerCase();
+    const mediaType = MEDIA_TYPE_MAP[ext];
+    if (!mediaType) {
+        throw new Error(
+            `Unsupported image format: ${ext}. Supported formats: ${Object.keys(MEDIA_TYPE_MAP).join(', ')}`
+        );
+    }
+
+    let dataBuffer: Buffer;
+    try {
+        dataBuffer = await fsPromises.readFile(filePath) as Buffer;
+    } catch (err: any) {
+        if (err.code === 'ENOENT') {
+            throw new Error(`Image file not found: ${filePath}`);
+        }
+        throw err;
+    }
+
+    let finalMediaType = mediaType;
+    if (opts.maxDimension !== undefined) {
+        const resized = await resizeImage(dataBuffer, opts.maxDimension, mediaType);
+        dataBuffer = resized.buffer;
+        finalMediaType = resized.mediaType;
+    }
+
+    const content: InputImageContent = {
+        type: 'input_image',
+        image_data: dataBuffer.toString('base64'),
+        media_type: finalMediaType,
+    };
+    if (opts.detail !== undefined) {
+        content.detail = opts.detail;
+    }
+    return content;
+}
+
+/**
+ * Creates an `InputImageContent` part from a URL.
+ * The server will infer the media type from the URL.
+ *
+ * @param url - Public URL pointing to the image.
+ * @param detail - Optional detail level hint for the model ('low' | 'high' | 'auto').
+ * @returns An `InputImageContent` object with the image URL.
+ */
+export function createImageContentFromUrl(url: string, detail?: 'low' | 'high' | 'auto'): InputImageContent {
+    const content: InputImageContent = {
+        type: 'input_image',
+        image_url: url,
+        // media_type intentionally omitted — server infers from URL
+    };
+    if (detail !== undefined) {
+        content.detail = detail;
+    }
+    return content;
+}
+
+/**
+ * Attempts to resize image data to fit within `maxDimension` on the longest side.
+ * Requires the optional `sharp` peer dependency. Falls back to original data with a
+ * warning if `sharp` is not available.
+ * Returns both the (possibly resized) buffer and the media type.
+ */
+async function resizeImage(data: Buffer, maxDimension: number, fallbackMediaType: string): Promise<{ buffer: Buffer; mediaType: string }> {
+    let sharp: any;
+    try {
+        // Dynamic import so sharp remains a soft/optional peer dep.
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore — sharp is an optional peer dependency
+        sharp = (await import('sharp')).default;
+    } catch {
+        console.warn(
+            `[foundry-local] createImageContentFromFile: maxDimension=${maxDimension} requires the ` +
+            `"sharp" package (npm install sharp). Image will be used unresized.`
+        );
+        return { buffer: data, mediaType: fallbackMediaType };
+    }
+
+    const metadata = await sharp(data).metadata();
+    const { width = 0, height = 0, format } = metadata;
+    // Map sharp format names back to MIME types; fall back to the original type
+    const formatToMime: Record<string, string> = {
+        png: 'image/png', jpeg: 'image/jpeg', gif: 'image/gif',
+        webp: 'image/webp', bmp: 'image/bmp',
+    };
+    const mediaType = (format && formatToMime[format]) ?? fallbackMediaType;
+
+    if (Math.max(width, height) <= maxDimension) {
+        return { buffer: data, mediaType };
+    }
+
+    const resizedBuffer: Buffer = await sharp(data)
+        .resize({ width: maxDimension, height: maxDimension, fit: 'inside', withoutEnlargement: true })
+        .toBuffer();
+
+    return { buffer: resizedBuffer, mediaType };
+}

sdk/js/src/types.ts

@@ -127,6 +127,20 @@ export interface InputTextContent {
     text: string;
 }
 
+export interface InputImageContent {
+    type: 'input_image';
+    image_url?: string;
+    image_data?: string;       // base64-encoded
+    media_type?: string;       // e.g. "image/png"; omit to let the server infer
+    detail?: 'low' | 'high' | 'auto';
+}
+
+export interface InputFileContent {
+    type: 'input_file';
+    filename: string;
+    file_url: string;
+}
+
 export interface OutputTextContent {
     type: 'output_text';
     text: string;
@@ -139,7 +153,7 @@ export interface RefusalContent {
     refusal: string;
 }
 
-export type ContentPart = InputTextContent | OutputTextContent | RefusalContent;
+export type ContentPart = InputTextContent | InputImageContent | InputFileContent | OutputTextContent | RefusalContent;
 
 export interface Annotation {
     type: string;
@@ -419,6 +433,55 @@ export interface FunctionCallArgsDoneEvent {
     sequence_number: number;
 }
 
+export interface ReasoningSummaryPartAddedEvent {
+    type: 'response.reasoning_summary_part.added';
+    item_id: string;
+    part: ContentPart;
+    sequence_number: number;
+}
+
+export interface ReasoningSummaryPartDoneEvent {
+    type: 'response.reasoning_summary_part.done';
+    item_id: string;
+    part: ContentPart;
+    sequence_number: number;
+}
+
+export interface ReasoningDeltaEvent {
+    type: 'response.reasoning.delta';
+    item_id: string;
+    delta: string;
+    sequence_number: number;
+}
+
+export interface ReasoningDoneEvent {
+    type: 'response.reasoning.done';
+    item_id: string;
+    text: string;
+    sequence_number: number;
+}
+
+export interface ReasoningSummaryTextDeltaEvent {
+    type: 'response.reasoning_summary_text.delta';
+    item_id: string;
+    delta: string;
+    sequence_number: number;
+}
+
+export interface ReasoningSummaryTextDoneEvent {
+    type: 'response.reasoning_summary_text.done';
+    item_id: string;
+    text: string;
+    sequence_number: number;
+}
+
+export interface OutputTextAnnotationAddedEvent {
+    type: 'response.output_text.annotation.added';
+    item_id: string;
+    annotation: Annotation;
+    sequence_number: number;
+}
+
 export interface StreamingErrorEvent {
     type: 'error';
     code?: string;
@@ -439,4 +502,18 @@ export type StreamingEvent =
     | RefusalDoneEvent
     | FunctionCallArgsDeltaEvent
     | FunctionCallArgsDoneEvent
+    | ReasoningSummaryPartAddedEvent
+    | ReasoningSummaryPartDoneEvent
+    | ReasoningDeltaEvent
+    | ReasoningDoneEvent
+    | ReasoningSummaryTextDeltaEvent
+    | ReasoningSummaryTextDoneEvent
+    | OutputTextAnnotationAddedEvent
     | StreamingErrorEvent;
+
+// --- List Responses ---
+
+export interface ListResponsesResult {
+    object: 'list';
+    data: ResponseObject[];
+}