@meetopenbot/openbot 0.2.6 → 1.0.0

package/dist/runtime.js

@@ -1,518 +1,413 @@
-import { generateText } from 'ai';
+import { streamText, stepCountIs } from 'ai';
 import { eventsToModelMessages } from './history.js';
 import { buildContext } from './context.js';
 import { OPENBOT_SYSTEM_PROMPT } from './system-prompt.js';
 import { isAuthErrorMessage, isCreditsErrorMessage } from '@meetopenbot/plugin-sdk';
-import { AUTO_MODEL_ID, isAutoModel, isRetryableModelError, listAutoModelCandidates, } from './auto-model.js';
-import { resolveModel } from './model.js';
+import { AUTO_MODEL_ID, isAutoModel, isRetryableModelError, listAutoModelCandidates, missingByokApiKeyMessage, } from './auto-model.js';
+import { includeReasoningInHistory, reasoningForModel, resolveModel } from './model.js';
 import { fetchModelRegistry, getProviderModelOptions, listApiKeyProviders, PROVIDER_API_KEY_LINKS, } from '@meetopenbot/plugin-sdk';
+import { errorFromStreamPart } from './stream-error.js';
+import { createAgentOutputBuffer, isOutputBoundaryPart } from './output-buffer.js';
 async function buildSystemPrompt(state, storage) {
     const context = await buildContext(state, storage);
     const sections = [OPENBOT_SYSTEM_PROMPT, '', context];
-    // Hardcoded naming hint logic
     const threadState = state.threadDetails?.state;
     if (!threadState?.isSmartNamed) {
-        sections.push('', '## SYSTEM HINT', 'This thread is unnamed. Please use the `patch_thread_details` tool to set a concise, descriptive, and regular `name` (e.g., "Project Brainstorming" instead of "project-brainstorm") in the thread state and set `isSmartNamed: true` in the same patch. Only do this once.');
+        sections.push('', '## SYSTEM HINT', 'This thread is unnamed. Please use the `set_thread_title` tool to set a concise, descriptive title (e.g., "Project Brainstorming" instead of "project-brainstorm"). Only do this once.');
     }
     return sections.join('\n');
 }
-/**
- * Tracks tool-call IDs from one LLM turn until matching `:result` events arrive.
- *
- * Melony runs yielded `action:*` events depth-first, so parallel tool calls from
- * a single `generateText` response execute one-by-one. We must wait for every ID
- * in the batch before calling the LLM again — not after the first result.
- */
-function createToolBatchTracker(state, storage, channelId, threadId) {
-    const save = async (ids) => {
-        if (!storage || !channelId || !threadId)
-            return;
-        try {
-            await storage.patchThreadState({
-                channelId,
-                threadId,
-                state: { pendingToolCallIds: ids },
-            });
-        }
-        catch (error) {
-            console.error('[openbot] Failed to persist pendingToolCallIds:', error);
-        }
-    };
-    return {
-        async startBatch(toolCallIds) {
-            state.pendingToolCallIds = [...toolCallIds];
-            await save(state.pendingToolCallIds);
-        },
-        async clear() {
-            state.pendingToolCallIds = undefined;
-            await save(undefined);
-        },
-        /** Returns true when this result completes the batch (time to call the LLM again). */
-        async recordResult(toolCallId) {
-            if (!state.pendingToolCallIds?.includes(toolCallId))
-                return false;
-            state.pendingToolCallIds = state.pendingToolCallIds.filter((id) => id !== toolCallId);
-            const done = state.pendingToolCallIds.length === 0;
-            if (done) {
-                state.pendingToolCallIds = undefined;
-            }
-            await save(state.pendingToolCallIds);
-            return done;
-        },
-    };
+function toAiTools(tools, args, flushPendingOutput) {
+    const mapped = {};
+    for (const [name, def] of Object.entries(tools)) {
+        if (!def.execute)
+            continue;
+        mapped[name] = {
+            description: def.description,
+            inputSchema: def.inputSchema,
+            execute: async (input, { toolCallId }) => {
+                await flushPendingOutput();
+                await args.emit({
+                    type: `action:${name}`,
+                    data: input,
+                    meta: {
+                        toolCallId,
+                        agentId: args.context.agentId,
+                        threadId: args.threadId,
+                    },
+                });
+                try {
+                    const result = await def.execute(input, {
+                        agentId: args.context.agentId,
+                        channelId: args.state.channelId,
+                        threadId: args.threadId,
+                        runId: args.state.runId,
+                        toolCallId,
+                        abortSignal: args.context.abortSignal,
+                        storage: args.context.storage,
+                        host: args.context.host,
+                        publicBaseUrl: args.context.publicBaseUrl,
+                        config: args.context.config,
+                        state: args.state,
+                        emit: args.emit,
+                    });
+                    const data = typeof result === 'string'
+                        ? { success: true, output: result }
+                        : { success: result.success !== false, ...result };
+                    await args.emit({
+                        type: `action:${name}:result`,
+                        data,
+                        meta: {
+                            toolCallId,
+                            agentId: args.context.agentId,
+                            threadId: args.threadId,
+                        },
+                    });
+                    return data.output ?? JSON.stringify(data);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    await args.emit({
+                        type: `action:${name}:result`,
+                        data: { success: false, error: message, output: message },
+                        meta: {
+                            toolCallId,
+                            agentId: args.context.agentId,
+                            threadId: args.threadId,
+                        },
+                    });
+                    return message;
+                }
+            },
+        };
+    }
+    return mapped;
 }
-/**
- * OpenBot agent runtime.
- *
- * - One `generateText` call per `runLLM` (tools have no `execute`; SDK stops at 1 step).
- * - Tool calls become `action:*` events; plugins emit `:result` when done.
- * - When a full batch of results is in, `runLLM` runs again with updated history.
- */
-export const openbotRuntime = (options) => (builder) => {
-    const { model: modelString = AUTO_MODEL_ID, authMode = 'byok', agentId, storage, toolDefinitions = {}, abortSignal, host, } = options;
+export async function* runOpenbotTurn(args, options) {
+    const { model: modelString = AUTO_MODEL_ID, authMode = 'byok', storage, toolDefinitions = {}, abortSignal, host, } = options;
     let configuredModelString = modelString;
     const isCreditsCloudAgent = (id) => host.isCloudSystemAgent(id ?? '') && authMode === 'credits';
-    const runLLM = async function* (context, threadId, trigger) {
-        if (!storage)
-            return;
-        if (abortSignal?.aborted)
-            return;
-        const toolBatch = createToolBatchTracker(context.state, storage, context.state.channelId, threadId || context.state.threadId);
-        // Capture parent metadata for event enrichment
-        const triggerEvent = trigger || context.state.triggerEvent;
-        const parentAgentId = triggerEvent?.meta?.parentAgentId;
-        const parentToolCallId = triggerEvent?.meta?.parentToolCallId;
-        const state = context.state;
-        state.model = configuredModelString;
-        const systemPrompt = await buildSystemPrompt(context.state, storage);
-        const events = await storage.getEvents({
-            channelId: context.state.channelId,
-            threadId: context.state.threadId,
-        });
-        const messages = eventsToModelMessages(events);
-        const candidates = isAutoModel(configuredModelString)
-            ? listAutoModelCandidates({ authMode })
-            : [configuredModelString];
-        try {
-            // Single LLM request — tool execution happens externally via action:* handlers.
-            const generate = async () => {
-                let lastError;
-                for (let i = 0; i < candidates.length; i++) {
-                    try {
-                        return await generateText({
-                            model: resolveModel(candidates[i], { authMode }),
-                            system: systemPrompt,
-                            messages,
-                            tools: toolDefinitions,
-                            stopWhen: ({ steps }) => steps.length === 1,
-                            allowSystemInMessages: true,
-                            abortSignal,
-                        });
+    if (!storage || abortSignal?.aborted)
+        return;
+    const state = args.state;
+    state.model = configuredModelString;
+    const threadId = args.threadId || state.threadId;
+    const systemPrompt = await buildSystemPrompt(state, storage);
+    const events = await storage.getEvents({
+        channelId: state.channelId ?? '',
+        threadId,
+    });
+    const candidates = isAutoModel(configuredModelString)
+        ? listAutoModelCandidates({ authMode })
+        : [configuredModelString];
+    try {
+        const missingKey = missingByokApiKeyMessage(configuredModelString, { authMode });
+        if (missingKey)
+            throw new Error(missingKey);
+        let lastError;
+        let started = false;
+        for (let i = 0; i < candidates.length; i++) {
+            const candidate = candidates[i];
+            const output = createAgentOutputBuffer({ agentId: state.agentId, threadId });
+            const flushPendingOutput = async () => {
+                const event = output.take();
+                if (event)
+                    await args.emit(event);
+            };
+            const tools = toAiTools(toolDefinitions, args, flushPendingOutput);
+            try {
+                const result = streamText({
+                    model: resolveModel(candidate, { authMode }),
+                    system: systemPrompt,
+                    messages: eventsToModelMessages(events, {
+                        includeReasoning: includeReasoningInHistory(candidate),
+                    }),
+                    tools,
+                    abortSignal,
+                    reasoning: reasoningForModel(candidate),
+                    stopWhen: stepCountIs(20),
+                    allowSystemInMessages: true,
+                });
+                for await (const part of result.fullStream) {
+                    if (abortSignal?.aborted)
+                        return;
+                    const streamError = errorFromStreamPart(part);
+                    if (streamError)
+                        throw streamError;
+                    if (part.type === 'text-delta' && part.text) {
+                        output.addText(part.text);
+                        yield {
+                            type: 'agent:output:delta',
+                            data: { content: part.text },
+                            meta: { agentId: state.agentId, threadId },
+                        };
                     }
-                    catch (error) {
-                        lastError = error;
-                        if (abortSignal?.aborted)
-                            throw error;
-                        const errorMessage = error instanceof Error ? error.message : String(error);
-                        if (isCreditsErrorMessage(errorMessage) || isAuthErrorMessage(errorMessage)) {
-                            throw error;
-                        }
-                        if (!isRetryableModelError(error) || i === candidates.length - 1) {
-                            throw error;
-                        }
+                    if (part.type === 'reasoning-delta' && 'text' in part && part.text) {
+                        output.addReasoning(part.text);
+                        yield {
+                            type: 'agent:output:delta',
+                            data: { reasoning: part.text },
+                            meta: { agentId: state.agentId, threadId },
+                        };
+                    }
+                    if (isOutputBoundaryPart(part.type)) {
+                        const event = output.take();
+                        if (event)
+                            yield event;
                     }
                 }
-                throw lastError ?? new Error('Model request failed.');
-            };
-            const result = await generate();
-            const toolCalls = result.toolCalls ?? [];
-            // if (result.usage) {
-            //   const usage = result.usage;
-            //   yield {
-            //     type: 'agent:usage',
-            //     data: {
-            //       usage: {
-            //         promptTokens: usage.inputTokens,
-            //         completionTokens: usage.outputTokens,
-            //         totalTokens: usage.totalTokens,
-            //         currentContextTokens: usage.inputTokens,
-            //         contextBudget: getContextBudgetForModel(currentModelString),
-            //       },
-            //       model: currentModelString,
-            //     },
-            //     meta: {
-            //       agentId: context.state.agentId,
-            //       threadId,
-            //       runId: context.state.runId,
-            //     },
-            //   } as OpenBotEvent;
-            // }
-            const outputMeta = {
-                agentId: context.state.agentId,
-                threadId,
-                parentAgentId,
-                parentToolCallId,
-            };
-            // Text before actions so history/UI show the model's intent first.
-            if (result.text) {
-                yield {
-                    type: 'agent:output',
-                    data: { content: result.text },
-                    meta: outputMeta,
-                };
-            }
-            if (toolCalls.length > 0) {
-                // when multiple tool calls are made, Melony runtime handles them one by one, thats why we need to start a new batch
-                await toolBatch.startBatch(toolCalls.map((tc) => tc.toolCallId));
-                for (const toolCall of toolCalls) {
-                    yield {
-                        type: `action:${toolCall.toolName}`,
-                        data: toolCall.input,
-                        meta: {
-                            toolCallId: toolCall.toolCallId,
-                            ...outputMeta,
-                        },
-                    };
-                }
-            }
-            else {
-                // clear the tool batch if there are no tool calls
-                await toolBatch.clear();
+                const leftover = output.take();
+                if (leftover)
+                    yield leftover;
+                started = true;
+                lastError = undefined;
+                break;
             }
-        }
-        catch (error) {
-            // Run was stopped — unwind quietly without surfacing an error.
-            if (abortSignal?.aborted)
-                return;
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            if (isCreditsCloudAgent(context.state.agentId)) {
-                if (isCreditsErrorMessage(errorMessage)) {
-                    yield {
-                        type: 'agent:output',
-                        data: {
-                            content: 'Insufficient workspace credits. Add credits in workspace settings or switch this agent to BYOK mode.',
-                        },
-                        meta: { agentId: context.state.agentId, threadId },
-                    };
+            catch (error) {
+                lastError = error;
+                if (abortSignal?.aborted)
                     return;
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (isCreditsErrorMessage(errorMessage) || isAuthErrorMessage(errorMessage)) {
+                    throw error;
                 }
-                if (isAuthErrorMessage(errorMessage)) {
-                    yield {
-                        type: 'agent:output',
-                        data: {
-                            content: 'Could not authenticate via OpenBot Credits. Check your workspace credit balance in settings, or switch this agent to BYOK mode.',
-                        },
-                        meta: { agentId: context.state.agentId, threadId },
-                    };
-                    return;
+                if (!isRetryableModelError(error) || i === candidates.length - 1) {
+                    throw error;
                 }
             }
-            if (isAuthErrorMessage(errorMessage) && !isCreditsCloudAgent(context.state.agentId)) {
-                const registry = await fetchModelRegistry();
-                const providerActions = listApiKeyProviders(registry).map((provider) => ({
-                    id: provider.id,
-                    label: provider.label,
-                    variant: 'primary',
-                }));
+        }
+        if (!started && lastError)
+            throw lastError;
+    }
+    catch (error) {
+        if (abortSignal?.aborted)
+            return;
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (isCreditsCloudAgent(state.agentId)) {
+            if (isCreditsErrorMessage(errorMessage)) {
                 yield {
-                    type: 'client:ui:widget',
+                    type: 'agent:output',
                     data: {
-                        kind: 'choice',
-                        widgetId: `api_provider_selection_${Date.now()}`,
-                        title: `Setup AI Provider`,
-                        description: `Select a provider to continue.`,
-                        actions: providerActions,
-                        metadata: {
-                            type: 'api_provider_selection',
-                        },
+                        content: 'Insufficient workspace credits. Add credits in workspace settings or switch this agent to BYOK mode.',
                     },
-                    meta: { agentId: context.state.agentId, threadId },
+                    meta: { agentId: state.agentId, threadId },
                 };
                 return;
             }
-            throw error;
-        }
-    };
-    builder.on('agent:invoke', async function* (event, context) {
-        const routedTo = event.data?.agentId;
-        if (typeof routedTo === 'string' && routedTo && routedTo !== context.state.agentId) {
-            return;
-        }
-        // Capture user info from meta if available
-        if (event.meta?.userName) {
-            context.state.currentUser = {
-                userName: event.meta.userName,
-            };
-        }
-        const threadId = event.meta?.threadId || context.state.threadId;
-        // clear the tool batch if the agent is invoked
-        // this is to prevent the tool batch from being used for a new agent invocation
-        await createToolBatchTracker(context.state, storage, context.state.channelId, threadId).clear();
-        yield* runLLM(context, threadId, event);
-    });
-    // this is to handle the tool results from the tool calls
-    // because Melony runtime handles them one by one, thats why we need to record the result
-    builder.on('*', async function* (event, context) {
-        if (!event.type.endsWith(':result'))
-            return;
-        if (event.meta?.agentId !== context.state.agentId)
-            return;
-        const toolCallId = event.meta?.toolCallId;
-        // record the result of the tool call
-        if (!toolCallId ||
-            !(await createToolBatchTracker(context.state, storage, context.state.channelId, event.meta?.threadId || context.state.threadId).recordResult(toolCallId)))
-            return;
-        const threadId = event.meta?.threadId || context.state.threadId;
-        yield* runLLM(context, threadId);
-    });
-    builder.on('client:ui:widget:response', async function* (event, context) {
-        const { metadata, values, actionId } = event.data;
-        const threadId = event.meta?.threadId || context.state.threadId;
-        if (isCreditsCloudAgent(context.state.agentId))
-            return;
-        if (metadata?.type === 'api_provider_selection') {
-            const provider = actionId;
-            const configuredModelId = isAutoModel(configuredModelString)
-                ? ''
-                : configuredModelString.split('/').slice(1).join('/');
-            const registry = await fetchModelRegistry();
-            const providerData = registry?.providers?.[provider];
-            const label = providerData?.label || provider;
-            const link = PROVIDER_API_KEY_LINKS[provider] || '';
-            const modelOptions = getProviderModelOptions(registry, provider);
-            yield {
-                type: 'client:ui:widget',
-                data: {
-                    widgetId: event.data.widgetId,
-                    kind: 'message',
-                    title: 'Provider Selected',
-                    body: `${label} provider was selected.`,
-                    state: 'submitted',
-                    display: 'collapsed',
-                    disabled: true,
-                    actions: [],
-                },
-                meta: { agentId: context.state.agentId, threadId },
-            };
-            if (modelOptions && modelOptions.length > 0 && !isAutoModel(configuredModelString)) {
-                const defaultModelId = modelOptions.find((m) => m.value === configuredModelId)?.value || modelOptions[0].value;
+            if (isAuthErrorMessage(errorMessage)) {
                 yield {
-                    type: 'client:ui:widget',
+                    type: 'agent:output',
                     data: {
-                        kind: 'choice',
-                        widgetId: `api_model_selection_${Date.now()}`,
-                        title: 'Select Model',
-                        description: `Choose a ${label} model.`,
-                        actions: modelOptions.map((option) => ({
-                            id: option.value,
-                            label: option.label,
-                            variant: option.value === defaultModelId ? 'primary' : 'secondary',
-                        })),
-                        metadata: {
-                            type: 'api_model_selection',
-                            provider,
-                        },
+                        content: 'Could not authenticate via OpenBot Credits. Check your workspace credit balance in settings, or switch this agent to BYOK mode.',
                     },
-                    meta: { agentId: context.state.agentId, threadId },
+                    meta: { agentId: state.agentId, threadId },
                 };
                 return;
             }
-            yield {
-                type: 'client:ui:widget',
-                data: {
-                    kind: 'form',
-                    widgetId: `api_key_request_${Date.now()}`,
-                    title: `${label} Setup`,
-                    description: isAutoModel(configuredModelString)
-                        ? `Enter your API key to continue.`
-                        : `Enter your API key and model ID.`,
-                    fields: [
-                        ...(isAutoModel(configuredModelString)
-                            ? []
-                            : [
-                                {
-                                    id: 'model',
-                                    label: 'Model',
-                                    type: 'text',
-                                    description: 'Enter the model ID for this provider.',
-                                    placeholder: provider === 'openai'
-                                        ? 'gpt-4o-mini'
-                                        : provider === 'anthropic'
-                                            ? 'claude-3-5-sonnet-20241022'
-                                            : provider === 'deepseek'
-                                                ? 'deepseek-chat'
-                                                : 'gemini-2.0-flash',
-                                    required: true,
-                                    defaultValue: configuredModelId || '',
-                                },
-                            ]),
-                        {
-                            id: 'apiKey',
-                            label: 'API Key',
-                            type: 'password',
-                            description: `Get your key here: [${link}](${link})`,
-                            placeholder: `sk-...`,
-                            required: true,
-                        },
-                    ],
-                    submitLabel: 'Save & Continue',
-                    metadata: {
-                        type: 'api_key_request',
-                        provider,
-                    },
-                },
-                meta: { agentId: context.state.agentId, threadId },
-            };
-            return;
         }
-        if (metadata?.type === 'api_model_selection') {
-            const provider = String(metadata.provider);
-            const modelId = String(actionId).trim();
+        if (isAuthErrorMessage(errorMessage) && !isCreditsCloudAgent(state.agentId)) {
             const registry = await fetchModelRegistry();
-            const providerData = registry?.providers?.[provider];
-            const label = providerData?.label || provider;
-            const modelLabel = providerData?.models.find((model) => model.id === modelId)?.label || modelId;
-            const link = PROVIDER_API_KEY_LINKS[provider] || '';
+            const providerActions = listApiKeyProviders(registry).map((provider) => ({
+                id: provider.id,
+                label: provider.label,
+                variant: 'primary',
+            }));
             yield {
                 type: 'client:ui:widget',
                 data: {
-                    widgetId: event.data.widgetId,
-                    kind: 'message',
-                    title: 'Model Selected',
-                    body: `${modelLabel} was selected.`,
-                    state: 'submitted',
-                    display: 'collapsed',
-                    disabled: true,
-                    actions: [],
+                    kind: 'choice',
+                    widgetId: `api_provider_selection_${Date.now()}`,
+                    title: `Setup AI Provider`,
+                    description: `Select a provider to continue.`,
+                    actions: providerActions,
+                    metadata: { type: 'api_provider_selection' },
                 },
-                meta: { agentId: context.state.agentId, threadId },
+                meta: { agentId: state.agentId, threadId },
             };
+            return;
+        }
+        throw error;
+    }
+}
+export async function* handleOpenbotWidgetResponse(args, options) {
+    const event = args.event;
+    const { metadata, values, actionId } = event.data;
+    const threadId = args.threadId;
+    const { host, storage } = options;
+    let configuredModelString = options.model ?? AUTO_MODEL_ID;
+    const state = args.state;
+    if (host.isCloudSystemAgent(state.agentId) && options.authMode === 'credits')
+        return;
+    if (metadata?.type === 'api_provider_selection') {
+        const provider = actionId;
+        const configuredModelId = isAutoModel(configuredModelString)
+            ? ''
+            : configuredModelString.split('/').slice(1).join('/');
+        const registry = await fetchModelRegistry();
+        const providerData = registry?.providers?.[provider];
+        const label = providerData?.label || provider;
+        const link = PROVIDER_API_KEY_LINKS[provider] || '';
+        const modelOptions = getProviderModelOptions(registry, provider);
+        yield {
+            type: 'client:ui:widget',
+            data: {
+                widgetId: event.data.widgetId,
+                kind: 'message',
+                title: 'Provider Selected',
+                body: `${label} provider was selected.`,
+                state: 'submitted',
+                display: 'collapsed',
+                disabled: true,
+                actions: [],
+            },
+            meta: { agentId: state.agentId, threadId },
+        };
+        if (modelOptions && modelOptions.length > 0 && !isAutoModel(configuredModelString)) {
+            const defaultModelId = modelOptions.find((m) => m.value === configuredModelId)?.value || modelOptions[0].value;
             yield {
                 type: 'client:ui:widget',
                 data: {
-                    kind: 'form',
-                    widgetId: `api_key_request_${Date.now()}`,
-                    title: `${label} Setup`,
-                    description: `Enter your API key to continue.`,
-                    fields: [
-                        {
-                            id: 'apiKey',
-                            label: 'API Key',
-                            type: 'password',
-                            description: `Get your key here: [${link}](${link})`,
-                            placeholder: `sk-...`,
-                            required: true,
-                        },
-                    ],
-                    submitLabel: 'Save & Continue',
-                    metadata: {
-                        type: 'api_key_request',
-                        provider,
-                        model: modelId,
-                    },
+                    kind: 'choice',
+                    widgetId: `api_model_selection_${Date.now()}`,
+                    title: 'Select Model',
+                    description: `Choose a ${label} model.`,
+                    actions: modelOptions.map((option) => ({
+                        id: option.value,
+                        label: option.label,
+                        variant: option.value === defaultModelId ? 'primary' : 'secondary',
+                    })),
+                    metadata: { type: 'api_model_selection', provider },
                 },
-                meta: { agentId: context.state.agentId, threadId },
-            };
-            return;
-        }
-        if (metadata?.type !== 'api_key_request')
-            return;
-        if (!values?.apiKey)
-            return;
-        const provider = String(values.provider || metadata.provider);
-        const keepAuto = isAutoModel(configuredModelString);
-        const modelId = String(values.model || metadata.model || '').trim();
-        if (!keepAuto && !modelId)
-            return;
-        const apiKey = String(values.apiKey);
-        if (provider !== 'openai' &&
-            provider !== 'anthropic' &&
-            provider !== 'google' &&
-            provider !== 'deepseek') {
-            yield {
-                type: 'agent:output',
-                data: { content: `Unsupported provider: ${provider}` },
-                meta: { agentId: context.state.agentId },
+                meta: { agentId: state.agentId, threadId },
             };
             return;
         }
-        const envVar = provider === 'openai'
-            ? 'OPENAI_API_KEY'
-            : provider === 'anthropic'
-                ? 'ANTHROPIC_API_KEY'
-                : provider === 'deepseek'
-                    ? 'DEEPSEEK_API_KEY'
-                    : 'GOOGLE_GENERATIVE_AI_API_KEY';
-        const newModelString = keepAuto ? AUTO_MODEL_ID : `${provider}/${modelId}`;
-        if (!storage)
-            return;
-        try {
-            await storage.createVariable({ key: envVar, value: apiKey, secret: true });
-            process.env[envVar] = apiKey;
-            if (!keepAuto) {
-                configuredModelString = newModelString;
-            }
-            try {
-                if (!keepAuto) {
-                    host.saveConfig({ model: configuredModelString });
-                }
-                const details = await storage.getAgentDetails({ agentId: context.state.agentId });
-                const updatedPlugins = details.pluginRefs.map((ref) => {
-                    if (ref.id === host.openbotPluginId) {
-                        return {
-                            ...ref,
-                            config: {
-                                ...ref.config,
-                                ...(keepAuto ? {} : { model: configuredModelString }),
-                                ...(host.isCloudSystemAgent(context.state.agentId) ? { authMode: 'byok' } : {}),
+        yield {
+            type: 'client:ui:widget',
+            data: {
+                kind: 'form',
+                widgetId: `api_key_request_${Date.now()}`,
+                title: `${label} Setup`,
+                description: isAutoModel(configuredModelString)
+                    ? `Enter your API key to continue.`
+                    : `Enter your API key and model ID.`,
+                fields: [
+                    ...(isAutoModel(configuredModelString)
+                        ? []
+                        : [
+                            {
+                                id: 'model',
+                                label: 'Model',
+                                type: 'text',
+                                required: true,
+                                defaultValue: configuredModelId || '',
                             },
-                        };
-                    }
-                    return ref;
-                });
-                await storage.updateAgent({
-                    agentId: context.state.agentId,
-                    plugins: updatedPlugins,
-                });
-            }
-            catch {
-                // best-effort: config persistence failure shouldn't block the conversation
-            }
-            yield {
-                type: 'agent:output',
-                data: {
-                    content: keepAuto
-                        ? `Saved ${provider} API key. Auto will use it when that provider is the cheapest available.`
-                        : `Saved ${provider} API key and set model to \`${newModelString}\`.`,
-                },
-                meta: { agentId: context.state.agentId },
-            };
-            yield {
-                type: 'client:ui:widget',
-                data: {
-                    widgetId: event.data.widgetId,
-                    kind: 'message',
-                    title: 'API Key Saved',
-                    body: keepAuto
-                        ? `Successfully saved ${provider} API key. You can now continue your conversation.`
-                        : `Successfully saved ${provider} API key and selected model \`${newModelString}\`. You can now continue your conversation.`,
-                    state: 'submitted',
-                    display: 'collapsed',
-                    disabled: true,
-                    actions: [],
-                },
-                meta: { agentId: context.state.agentId },
-            };
-            yield* runLLM(context, threadId);
+                        ]),
+                    {
+                        id: 'apiKey',
+                        label: 'API Key',
+                        type: 'password',
+                        description: `Get your key here: [${link}](${link})`,
+                        required: true,
+                    },
+                ],
+                submitLabel: 'Save & Continue',
+                metadata: { type: 'api_key_request', provider },
+            },
+            meta: { agentId: state.agentId, threadId },
+        };
+        return;
+    }
+    if (metadata?.type === 'api_model_selection') {
+        const provider = String(metadata.provider);
+        const modelId = String(actionId).trim();
+        const registry = await fetchModelRegistry();
+        const providerData = registry?.providers?.[provider];
+        const label = providerData?.label || provider;
+        const link = PROVIDER_API_KEY_LINKS[provider] || '';
+        yield {
+            type: 'client:ui:widget',
+            data: {
+                widgetId: event.data.widgetId,
+                kind: 'message',
+                title: 'Model Selected',
+                body: `${modelId} was selected.`,
+                state: 'submitted',
+                display: 'collapsed',
+                disabled: true,
+                actions: [],
+            },
+            meta: { agentId: state.agentId, threadId },
+        };
+        yield {
+            type: 'client:ui:widget',
+            data: {
+                kind: 'form',
+                widgetId: `api_key_request_${Date.now()}`,
+                title: `${label} Setup`,
+                description: `Enter your API key to continue.`,
+                fields: [
+                    {
+                        id: 'apiKey',
+                        label: 'API Key',
+                        type: 'password',
+                        description: `Get your key here: [${link}](${link})`,
+                        required: true,
+                    },
+                ],
+                submitLabel: 'Save & Continue',
+                metadata: { type: 'api_key_request', provider, model: modelId },
+            },
+            meta: { agentId: state.agentId, threadId },
+        };
+        return;
+    }
+    if (metadata?.type !== 'api_key_request' || !values?.apiKey || !storage)
+        return;
+    const provider = String(values.provider || metadata.provider);
+    const keepAuto = isAutoModel(configuredModelString);
+    const modelId = String(values.model || metadata.model || '').trim();
+    if (!keepAuto && !modelId)
+        return;
+    const apiKey = String(values.apiKey);
+    if (provider !== 'openai' &&
+        provider !== 'anthropic' &&
+        provider !== 'google' &&
+        provider !== 'deepseek') {
+        yield {
+            type: 'agent:output',
+            data: { content: `Unsupported provider: ${provider}` },
+            meta: { agentId: state.agentId },
+        };
+        return;
+    }
+    const envVar = provider === 'openai'
+        ? 'OPENAI_API_KEY'
+        : provider === 'anthropic'
+            ? 'ANTHROPIC_API_KEY'
+            : provider === 'deepseek'
+                ? 'DEEPSEEK_API_KEY'
+                : 'GOOGLE_GENERATIVE_AI_API_KEY';
+    const newModelString = keepAuto ? AUTO_MODEL_ID : `${provider}/${modelId}`;
+    await storage.createVariable({ key: envVar, value: apiKey, secret: true });
+    process.env[envVar] = apiKey;
+    if (!keepAuto) {
+        configuredModelString = newModelString;
+        try {
+            host.saveConfig({ model: configuredModelString });
         }
-        catch (error) {
-            yield {
-                type: 'agent:output',
-                data: {
-                    content: `Failed to save API key: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-                meta: { agentId: context.state.agentId },
-            };
+        catch {
+            /* ignore */
         }
-    });
-};
+    }
+    yield {
+        type: 'agent:output',
+        data: {
+            content: keepAuto
+                ? `Saved ${provider} API key. Auto will use it when that provider is the cheapest available.`
+                : `Saved ${provider} API key and set model to \`${newModelString}\`.`,
+        },
+        meta: { agentId: state.agentId },
+    };
+    yield* runOpenbotTurn(args, { ...options, model: configuredModelString });
+}