@cogitator-ai/openai-compat 19.0.16 → 20.0.0

package/dist/client/openai-adapter.js

@@ -1,46 +1,81 @@
 /**
  * OpenAI SDK Adapter
  *
- * Allows using the OpenAI SDK to interact with Cogitator.
- * Creates an in-process adapter that can be used with the SDK's baseURL.
+ * Implements the OpenAI Assistants API semantics on top of Cogitator.
  */
 import { Agent } from '@cogitator-ai/core';
 import { EventEmitter } from 'events';
-import { ThreadManager } from './thread-manager.js';
 import { nanoid } from 'nanoid';
+import { z } from 'zod';
+import { ThreadManager } from './thread-manager.js';
+export const COGITATOR_MODEL_ID = 'cogitator';
+const ACTIVE_STATUSES = [
+    'queued',
+    'in_progress',
+    'requires_action',
+    'cancelling',
+];
+const RUN_TTL_SECONDS = 600;
+class RunTerminatedError extends Error {
+    status;
+    constructor(status) {
+        super(status === 'cancelled' ? 'Run was cancelled' : 'Run expired waiting for tool outputs');
+        this.status = status;
+        this.name = 'RunTerminatedError';
+    }
+}
+function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+function isActive(status) {
+    return ACTIVE_STATUSES.includes(status);
+}
+function toAgentResponseFormat(format) {
+    if (!format || format === 'auto' || format.type === 'text')
+        return {};
+    if (format.type === 'json_object')
+        return { responseFormat: { type: 'json' } };
+    return {
+        responseFormat: { type: 'json' },
+        instructions: `Respond with a JSON object that matches this JSON Schema (${format.json_schema.name}):\n${JSON.stringify(format.json_schema.schema)}`,
+    };
+}
+function toZodParameters(schema) {
+    try {
+        return z.fromJSONSchema(schema ?? { type: 'object', properties: {} });
+    }
+    catch {
+        return z.record(z.string(), z.unknown());
+    }
+}
+function renderTranscript(messages) {
+    return messages
+        .map((m) => `${m.role === 'assistant' ? 'Assistant' : 'User'}: ${m.content}`)
+        .join('\n\n');
+}
 /**
  * OpenAI SDK Adapter
  *
  * @example
  * ```typescript
- * import OpenAI from 'openai';
- * import { createOpenAIAdapter } from '@cogitator-ai/openai-compat';
- *
- * const adapter = createOpenAIAdapter(cogitator, {
- *   tools: [calculator, datetime],
- * });
- *
- * const openai = new OpenAI({
- *   apiKey: 'not-needed',
- *   baseURL: adapter.baseURL,
- * });
- *
- * // Use OpenAI SDK as normal
- * const assistant = await openai.beta.assistants.create({
- *   model: 'gpt-4o',
- *   name: 'My Assistant',
- * });
+ * const adapter = createOpenAIAdapter(cogitator, { tools: [calculator] });
+ * const assistant = await adapter.createAssistant({ model: 'openai/gpt-4o' });
  * ```
  */
 export class OpenAIAdapter {
     cogitator;
     threadManager;
     runs = new Map();
+    activeRunByThread = new Map();
     tools;
+    defaultModel;
+    maxStoredRuns;
     constructor(cogitator, options) {
         this.cogitator = cogitator;
-        this.threadManager = new ThreadManager();
+        this.threadManager = new ThreadManager(options?.storage);
         this.tools = options?.tools ?? [];
+        this.defaultModel = options?.defaultModel;
+        this.maxStoredRuns = options?.maxStoredRuns ?? 10_000;
     }
     /**
      * Get the thread manager for direct access
@@ -73,12 +108,14 @@ export class OpenAIAdapter {
             object: 'assistant',
             created_at: stored.created_at,
             name: stored.name,
-            description: null,
+            description: stored.description ?? null,
             model: stored.model,
             instructions: stored.instructions,
             tools: stored.tools,
             metadata: stored.metadata,
             temperature: stored.temperature,
+            top_p: stored.top_p,
+            response_format: stored.response_format,
         };
     }
     async createThread(metadata) {
@@ -103,7 +140,10 @@ export class OpenAIAdapter {
         return this.threadManager.listMessages(threadId, options);
     }
     /**
-     * Create and execute a run
+     * Create a run and start executing it in the background.
+     *
+     * Rejects when the assistant or thread does not exist, or when the thread
+     * already has an active run.
      */
     async createRun(threadId, request) {
         const assistant = await this.threadManager.getAssistant(request.assistant_id);
@@ -114,8 +154,12 @@ export class OpenAIAdapter {
         if (!thread) {
             throw new Error(`Thread ${threadId} not found`);
         }
+        const activeRunId = this.activeRunByThread.get(threadId);
+        if (activeRunId) {
+            throw new Error(`Thread ${threadId} already has an active run ${activeRunId}.`);
+        }
         const runId = `run_${nanoid()}`;
-        const now = Math.floor(Date.now() / 1000);
+        const now = nowSeconds();
         const run = {
             id: runId,
             object: 'thread.run',
@@ -125,7 +169,7 @@ export class OpenAIAdapter {
             status: 'queued',
             required_action: null,
             last_error: null,
-            expires_at: now + 600,
+            expires_at: now + RUN_TTL_SECONDS,
             started_at: null,
             cancelled_at: null,
             failed_at: null,
@@ -133,44 +177,44 @@ export class OpenAIAdapter {
             incomplete_details: null,
             model: request.model ?? assistant.model,
             instructions: request.instructions ?? assistant.instructions,
-            tools: (request.tools ?? assistant.tools),
+            tools: request.tools ?? assistant.tools,
             metadata: request.metadata ?? {},
             usage: null,
             temperature: request.temperature ?? assistant.temperature,
-            top_p: request.top_p,
+            top_p: request.top_p ?? assistant.top_p,
             max_prompt_tokens: request.max_prompt_tokens,
             max_completion_tokens: request.max_completion_tokens,
             truncation_strategy: request.truncation_strategy,
-            response_format: request.response_format,
+            response_format: request.response_format ?? assistant.response_format,
             tool_choice: request.tool_choice,
             parallel_tool_calls: request.parallel_tool_calls,
         };
-        const abortController = new AbortController();
-        const streamEmitter = request.stream ? new EventEmitter() : undefined;
-        this.runs.set(runId, { run, abortController, streamEmitter });
-        if (request.additional_messages) {
-            for (const msg of request.additional_messages) {
+        const state = {
+            run,
+            abortController: new AbortController(),
+            emitter: new EventEmitter(),
+            events: [],
+            ended: false,
+            pendingCalls: [],
+            flushScheduled: false,
+        };
+        this.runs.set(runId, state);
+        this.activeRunByThread.set(threadId, runId);
+        this.evictFinishedRuns();
+        try {
+            for (const msg of request.additional_messages ?? []) {
                 await this.threadManager.addMessage(threadId, msg);
             }
         }
-        streamEmitter?.emit('event', 'thread.run.created', run);
-        streamEmitter?.emit('event', 'thread.run.queued', run);
-        this.executeRun(runId, threadId, assistant, request, !!request.stream).catch((error) => {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            console.warn(`[OpenAIAdapter] Run ${runId} failed:`, errorMessage);
-            const state = this.runs.get(runId);
-            if (state) {
-                state.run.status = 'failed';
-                state.run.failed_at = Math.floor(Date.now() / 1000);
-                state.run.last_error = {
-                    code: 'server_error',
-                    message: errorMessage,
-                };
-                state.streamEmitter?.emit('event', 'thread.run.failed', state.run);
-                state.streamEmitter?.emit('end');
-            }
-        });
-        return run;
+        catch (error) {
+            this.runs.delete(runId);
+            this.activeRunByThread.delete(threadId);
+            throw error;
+        }
+        this.emit(state, 'thread.run.created', run);
+        this.emit(state, 'thread.run.queued', run);
+        void this.executeRun(state, assistant, request);
+        return structuredClone(run);
     }
     /**
      * Get a run by ID
@@ -178,25 +222,38 @@ export class OpenAIAdapter {
     getRun(threadId, runId) {
         const state = this.runs.get(runId);
         if (state?.run.thread_id === threadId) {
-            return state.run;
+            return structuredClone(state.run);
         }
         return undefined;
     }
     /**
-     * Cancel a run
+     * List runs of a thread, newest first
+     */
+    listRuns(threadId) {
+        return Array.from(this.runs.values())
+            .filter((state) => state.run.thread_id === threadId)
+            .map((state) => structuredClone(state.run))
+            .reverse();
+    }
+    /**
+     * Cancel a run. Throws when the run already finished.
      */
     cancelRun(threadId, runId) {
         const state = this.runs.get(runId);
-        if (state?.run.thread_id === threadId) {
-            state.abortController.abort();
-            state.run.status = 'cancelled';
-            state.run.cancelled_at = Math.floor(Date.now() / 1000);
-            return state.run;
+        if (state?.run.thread_id !== threadId) {
+            return undefined;
         }
-        return undefined;
+        if (!isActive(state.run.status) || state.run.status === 'cancelling') {
+            throw new Error(`Cannot cancel run with status '${state.run.status}'.`);
+        }
+        state.run.status = 'cancelling';
+        this.emit(state, 'thread.run.cancelling', state.run);
+        this.terminate(state, new RunTerminatedError('cancelled'));
+        return structuredClone(state.run);
     }
     /**
-     * Submit tool outputs for a run that requires action
+     * Submit outputs for the tool calls of a run that requires action.
+     * Outputs for every pending tool call must be provided.
      */
     async submitToolOutputs(threadId, runId, request) {
         const state = this.runs.get(runId);
@@ -204,53 +261,265 @@ export class OpenAIAdapter {
             return undefined;
         }
         if (state.run.status !== 'requires_action') {
-            throw new Error('Run is not waiting for tool outputs');
+            throw new Error(`Run is not waiting for tool outputs (status: '${state.run.status}').`);
         }
-        if (!state.toolOutputs) {
-            state.toolOutputs = new Map();
+        const outputs = new Map((request.tool_outputs ?? []).map((output) => [output.tool_call_id, output.output]));
+        const missing = state.pendingCalls.filter((pending) => !outputs.has(pending.call.id));
+        if (missing.length > 0) {
+            throw new Error(`Missing tool outputs for tool calls: ${missing.map((p) => p.call.id).join(', ')}`);
         }
-        for (const output of request.tool_outputs) {
-            state.toolOutputs.set(output.tool_call_id, output.output);
+        const unknown = [...outputs.keys()].filter((id) => !state.pendingCalls.some((pending) => pending.call.id === id));
+        if (unknown.length > 0) {
+            throw new Error(`Unknown tool call ids: ${unknown.join(', ')}`);
         }
+        const pending = state.pendingCalls;
+        state.pendingCalls = [];
+        this.clearExpiry(state);
         state.run.status = 'in_progress';
         state.run.required_action = null;
-        return state.run;
+        this.emit(state, 'thread.run.in_progress', state.run);
+        for (const call of pending) {
+            call.resolve(outputs.get(call.call.id) ?? '');
+        }
+        return structuredClone(state.run);
     }
     /**
-     * Get the stream emitter for a streaming run
+     * Get the event emitter of a run (all runs have one)
      */
     getStreamEmitter(runId) {
-        return this.runs.get(runId)?.streamEmitter;
+        return this.runs.get(runId)?.emitter;
+    }
+    /**
+     * Position in the run's event log; pass it to {@link streamRunEvents} to
+     * stream only events emitted after this point.
+     */
+    getRunEventCursor(runId) {
+        return this.runs.get(runId)?.events.length ?? 0;
     }
-    async executeRun(runId, threadId, assistant, request, streaming = false) {
+    /**
+     * Stream run events as server-sent-event payloads, starting at `fromIndex`
+     * of the run's event log (0 replays the whole run). The stream ends after the
+     * next `done` event, which follows a terminal status or `requires_action`.
+     */
+    async *streamRunEvents(runId, fromIndex = 0) {
         const state = this.runs.get(runId);
         if (!state)
             return;
-        const emitter = state.streamEmitter;
-        state.run.status = 'in_progress';
-        state.run.started_at = Math.floor(Date.now() / 1000);
-        emitter?.emit('event', 'thread.run.in_progress', state.run);
+        let index = fromIndex;
+        let wake = null;
+        const onEvent = () => {
+            if (wake) {
+                wake();
+                wake = null;
+            }
+        };
+        state.emitter.on('event', onEvent);
+        state.emitter.on('end', onEvent);
         try {
-            const messages = await this.threadManager.getMessagesForLLM(threadId);
+            while (true) {
+                if (index < state.events.length) {
+                    const event = state.events[index++];
+                    yield event;
+                    if (event.event === 'done')
+                        return;
+                    continue;
+                }
+                if (state.ended)
+                    return;
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+            }
+        }
+        finally {
+            state.emitter.off('event', onEvent);
+            state.emitter.off('end', onEvent);
+        }
+    }
+    emit(state, event, data) {
+        const payload = {
+            event,
+            data: typeof data === 'string' ? data : structuredClone(data),
+        };
+        state.events.push(payload);
+        state.emitter.emit('event', payload.event, payload.data);
+    }
+    end(state) {
+        if (state.ended)
+            return;
+        state.ended = true;
+        this.clearExpiry(state);
+        if (this.activeRunByThread.get(state.run.thread_id) === state.run.id) {
+            this.activeRunByThread.delete(state.run.thread_id);
+        }
+        state.emitter.emit('end');
+    }
+    clearExpiry(state) {
+        if (state.expiryTimer !== undefined) {
+            clearTimeout(state.expiryTimer);
+            state.expiryTimer = undefined;
+        }
+    }
+    terminate(state, reason) {
+        this.clearExpiry(state);
+        const pending = state.pendingCalls;
+        state.pendingCalls = [];
+        for (const call of pending)
+            call.reject(reason);
+        state.abortController.abort(reason);
+    }
+    evictFinishedRuns() {
+        if (this.runs.size <= this.maxStoredRuns)
+            return;
+        for (const [id, state] of this.runs) {
+            if (this.runs.size <= this.maxStoredRuns)
+                return;
+            if (state.ended)
+                this.runs.delete(id);
+        }
+    }
+    resolveModel(model) {
+        if (model !== COGITATOR_MODEL_ID)
+            return model;
+        if (!this.defaultModel) {
+            throw new Error(`Model '${COGITATOR_MODEL_ID}' requires the server to be configured with a defaultModel`);
+        }
+        return this.defaultModel;
+    }
+    /**
+     * Turn assistant `function` tools into Cogitator tools whose execution is
+     * delegated to the API client through `requires_action`.
+     */
+    createClientTools(state, definitions) {
+        return definitions.map((definition) => {
+            const parameters = toZodParameters(definition.parameters);
+            return {
+                name: definition.name,
+                description: definition.description ?? definition.name,
+                parameters,
+                execute: (args) => new Promise((resolve, reject) => {
+                    if (state.abortController.signal.aborted) {
+                        reject(new RunTerminatedError('cancelled'));
+                        return;
+                    }
+                    state.pendingCalls.push({
+                        call: {
+                            id: `call_${nanoid()}`,
+                            type: 'function',
+                            function: { name: definition.name, arguments: JSON.stringify(args ?? {}) },
+                        },
+                        resolve,
+                        reject,
+                    });
+                    this.scheduleRequiresAction(state);
+                }),
+                toJSON: () => {
+                    const schema = (definition.parameters ?? {});
+                    return {
+                        name: definition.name,
+                        description: definition.description ?? definition.name,
+                        parameters: {
+                            type: 'object',
+                            properties: schema.properties ?? {},
+                            required: schema.required,
+                        },
+                    };
+                },
+            };
+        });
+    }
+    scheduleRequiresAction(state) {
+        if (state.flushScheduled)
+            return;
+        state.flushScheduled = true;
+        setImmediate(() => {
+            state.flushScheduled = false;
+            if (state.pendingCalls.length === 0 || state.abortController.signal.aborted)
+                return;
+            state.run.status = 'requires_action';
+            state.run.required_action = {
+                type: 'submit_tool_outputs',
+                submit_tool_outputs: { tool_calls: state.pendingCalls.map((pending) => pending.call) },
+            };
+            state.run.expires_at = nowSeconds() + RUN_TTL_SECONDS;
+            this.emit(state, 'thread.run.requires_action', state.run);
+            this.emit(state, 'done', '[DONE]');
+            this.clearExpiry(state);
+            state.expiryTimer = setTimeout(() => {
+                this.terminate(state, new RunTerminatedError('expired'));
+            }, RUN_TTL_SECONDS * 1000);
+        });
+    }
+    async buildRunInput(threadId, request) {
+        let messages = await this.threadManager.getMessagesForLLM(threadId);
+        const truncation = request.truncation_strategy;
+        if (truncation?.type === 'last_messages' && truncation.last_messages) {
+            messages = messages.slice(-truncation.last_messages);
+        }
+        let lastUserIndex = -1;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === 'user') {
+                lastUserIndex = i;
+                break;
+            }
+        }
+        if (lastUserIndex === -1) {
+            throw new Error('No user message found');
+        }
+        const current = messages[lastUserIndex];
+        const prior = messages.slice(0, lastUserIndex);
+        const input = prior.length > 0
+            ? `Conversation so far:\n\n${renderTranscript(prior)}\n\nUser: ${current.content}`
+            : current.content;
+        return { input, images: current.images, hasHistory: prior.length > 0 };
+    }
+    async executeRun(state, assistant, request) {
+        const { run } = state;
+        const threadId = run.thread_id;
+        const signal = state.abortController.signal;
+        try {
+            run.status = 'in_progress';
+            run.started_at = nowSeconds();
+            this.emit(state, 'thread.run.in_progress', run);
+            const { input, images, hasHistory } = await this.buildRunInput(threadId, request);
+            const serverToolNames = new Set(this.tools.map((t) => t.name));
+            const functionDefinitions = run.tools.flatMap((t) => t.type === 'function' && !serverToolNames.has(t.function.name) ? [t.function] : []);
+            let tools = [...this.tools, ...this.createClientTools(state, functionDefinitions)];
+            const toolChoice = run.tool_choice;
+            if (toolChoice === 'none') {
+                tools = [];
+            }
+            else if (typeof toolChoice === 'object') {
+                tools = tools.filter((t) => t.name === toolChoice.function.name);
+            }
+            const format = toAgentResponseFormat(run.response_format);
+            const instructions = [
+                run.instructions ?? '',
+                request.additional_instructions ?? '',
+                format.instructions ?? '',
+            ]
+                .filter((part) => part.length > 0)
+                .join('\n\n');
             const agent = new Agent({
                 name: assistant.name ?? 'assistant',
-                model: request.model ?? assistant.model,
-                instructions: request.instructions ?? assistant.instructions ?? '',
-                temperature: request.temperature ?? assistant.temperature,
-                tools: this.tools,
+                model: this.resolveModel(run.model),
+                instructions,
+                temperature: run.temperature,
+                topP: run.top_p,
+                maxTokens: run.max_completion_tokens,
+                responseFormat: format.responseFormat,
+                tools,
             });
-            const lastUserMessage = messages.filter((m) => m.role === 'user').pop();
-            if (!lastUserMessage) {
-                throw new Error('No user message found');
-            }
             const messageId = `msg_${nanoid()}`;
-            let accumulatedContent = '';
-            let deltaIndex = 0;
-            if (streaming && emitter) {
-                const inProgressMessage = {
+            let messageAnnounced = false;
+            const announceMessage = () => {
+                if (messageAnnounced)
+                    return;
+                messageAnnounced = true;
+                const inProgress = {
                     id: messageId,
                     object: 'thread.message',
-                    created_at: Math.floor(Date.now() / 1000),
+                    created_at: nowSeconds(),
                     thread_id: threadId,
                     status: 'in_progress',
                     completed_at: null,
@@ -258,75 +527,85 @@ export class OpenAIAdapter {
                     role: 'assistant',
                     content: [],
                     assistant_id: assistant.id,
-                    run_id: runId,
+                    run_id: run.id,
                     attachments: [],
                     metadata: {},
                 };
-                emitter.emit('event', 'thread.message.created', inProgressMessage);
-                emitter.emit('event', 'thread.message.in_progress', inProgressMessage);
-            }
+                this.emit(state, 'thread.message.created', inProgress);
+                this.emit(state, 'thread.message.in_progress', inProgress);
+            };
+            let accumulated = '';
             const result = await this.cogitator.run(agent, {
-                input: lastUserMessage.content,
+                input,
+                images,
                 threadId,
-                stream: streaming,
-                onToken: streaming
-                    ? (token) => {
-                        accumulatedContent += token;
-                        if (emitter) {
-                            const delta = {
-                                id: messageId,
-                                object: 'thread.message.delta',
-                                delta: {
-                                    content: [
-                                        {
-                                            index: deltaIndex++,
-                                            type: 'text',
-                                            text: { value: token },
-                                        },
-                                    ],
-                                },
-                            };
-                            emitter.emit('event', 'thread.message.delta', delta);
-                        }
-                    }
-                    : undefined,
+                signal,
+                stream: !!request.stream,
+                parallelToolCalls: run.parallel_tool_calls,
+                ...(hasHistory && { loadHistory: false }),
+                onToken: (token) => {
+                    if (signal.aborted)
+                        return;
+                    announceMessage();
+                    accumulated += token;
+                    const delta = {
+                        id: messageId,
+                        object: 'thread.message.delta',
+                        delta: { content: [{ index: 0, type: 'text', text: { value: token } }] },
+                    };
+                    this.emit(state, 'thread.message.delta', delta);
+                },
             });
-            if (state.abortController.signal.aborted) {
-                return;
+            if (signal.aborted) {
+                throw signal.reason instanceof Error ? signal.reason : new RunTerminatedError('cancelled');
             }
-            const finalContent = result.output || accumulatedContent;
+            const finalContent = result.output || accumulated;
             if (finalContent) {
-                const message = await this.threadManager.addAssistantMessage(threadId, finalContent, assistant.id, runId);
-                if (streaming && emitter && message) {
-                    emitter.emit('event', 'thread.message.completed', message);
+                announceMessage();
+                const message = await this.threadManager.addAssistantMessage(threadId, finalContent, assistant.id, run.id, messageId);
+                if (message) {
+                    this.emit(state, 'thread.message.completed', message);
                 }
             }
-            state.run.status = 'completed';
-            state.run.completed_at = Math.floor(Date.now() / 1000);
-            state.run.usage = result.usage
+            run.status = 'completed';
+            run.completed_at = nowSeconds();
+            run.usage = result.usage
                 ? {
                     prompt_tokens: result.usage.inputTokens,
                     completion_tokens: result.usage.outputTokens,
                     total_tokens: result.usage.totalTokens,
                 }
                 : null;
-            emitter?.emit('event', 'thread.run.completed', state.run);
-            emitter?.emit('event', 'done', '[DONE]');
-            emitter?.emit('end');
+            this.emit(state, 'thread.run.completed', run);
         }
         catch (error) {
-            if (state.abortController.signal.aborted) {
-                return;
+            const reason = signal.aborted ? signal.reason : error;
+            if (reason instanceof RunTerminatedError) {
+                if (reason.status === 'cancelled') {
+                    run.status = 'cancelled';
+                    run.cancelled_at = nowSeconds();
+                    this.emit(state, 'thread.run.cancelled', run);
+                }
+                else {
+                    run.status = 'expired';
+                    this.emit(state, 'thread.run.expired', run);
+                }
             }
-            state.run.status = 'failed';
-            state.run.failed_at = Math.floor(Date.now() / 1000);
-            state.run.last_error = {
-                code: 'server_error',
-                message: error instanceof Error ? error.message : String(error),
-            };
-            emitter?.emit('event', 'thread.run.failed', state.run);
-            emitter?.emit('error', error instanceof Error ? error : new Error(String(error)));
-            emitter?.emit('end');
+            else {
+                run.status = 'failed';
+                run.failed_at = nowSeconds();
+                run.last_error = {
+                    code: 'server_error',
+                    message: error instanceof Error ? error.message : String(error),
+                };
+                this.emit(state, 'thread.run.failed', run);
+            }
+        }
+        finally {
+            run.required_action = null;
+            this.terminate(state, new RunTerminatedError('cancelled'));
+            this.emit(state, 'done', '[DONE]');
+            this.end(state);
         }
     }
 }