Guide AI connection setup with private node credentials and explicit providers

aiui/packages/app/src/__tests__/providerBridge.test.ts

@@ -0,0 +1,28 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { archyBridge } from '@/services/archyBridge'
+const originalParent = window.parent
+const origin = 'https://node.example'
+afterEach(() => { archyBridge.destroy(); Object.defineProperty(window, 'parent', { value: originalParent, configurable: true }); vi.restoreAllMocks() })
+describe('trusted provider setup bridge', () => {
+  it('accepts configuration only from the embedding parent, rejects siblings and other origins', () => {
+    const parent = { postMessage: vi.fn() }
+    Object.defineProperty(window, 'parent', { value: parent, configurable: true })
+    archyBridge.init(origin)
+    const listener = vi.fn(); const unsubscribe = archyBridge.onProviderConfigured(listener)
+    const send = (source: unknown, from: string, provider = 'openai') => window.dispatchEvent(new MessageEvent('message', { source: source as Window, origin: from, data: { type: 'ai:provider-configured', provider, model: 'test-model' } }))
+    send({}, origin); send(parent, 'https://evil.example'); send(parent, origin, 'arbitrary')
+    expect(listener).not.toHaveBeenCalled()
+    send(parent, origin)
+    expect(listener).toHaveBeenCalledExactlyOnceWith({ provider: 'openai', model: 'test-model' })
+    archyBridge.requestAISetup()
+    expect(parent.postMessage).toHaveBeenLastCalledWith({ type: 'ai:setup-request' }, origin)
+    unsubscribe()
+  })
+  it('replays the selection when the composer mounts after the handshake', () => {
+    const parent = { postMessage: vi.fn() }; Object.defineProperty(window, 'parent', { value: parent, configurable: true })
+    archyBridge.init(origin)
+    window.dispatchEvent(new MessageEvent('message', { source: parent as unknown as Window, origin, data: { type: 'ai:provider-configured', provider: 'local' } }))
+    const listener = vi.fn(); const unsubscribe = archyBridge.onProviderConfigured(listener)
+    expect(listener).toHaveBeenCalledExactlyOnceWith({ provider: 'local', model: '' }); unsubscribe()
+  })
+})

aiui/packages/app/src/__tests__/useAI.test.ts

@@ -249,6 +249,24 @@ describe('useAI', () => {
       expect(chatStore.isStreaming).toBe(false)
     })
 
+    it.each([502, 503, 429, 401])('distinguishes HTTP %s from a missing credential', async (status) => {
+      globalThis.fetch = vi.fn().mockResolvedValue({ ok: false, status, text: async () => 'Provider request failed' })
+      const store = useChatStore(); store.webSearchEnabled = false
+      const ai = useAI(); ai.needsApiKey.value = false
+      await ai.sendMessage('test')
+      expect(ai.needsApiKey.value).toBe(status === 401)
+      expect(store.isStreaming).toBe(false)
+    })
+
+    it('offers funding for a Routstr payment-required response without mislabeling it a key error', async () => {
+      globalThis.fetch = vi.fn().mockResolvedValue({ ok: false, status: 402, text: async () => JSON.stringify({ error: { message: 'Your spending allowance is exhausted' } }) })
+      const store = useChatStore(); store.webSearchEnabled = false
+      const ai = useAI(); ai.setProvider('routstr'); ai.needsApiKey.value = false; ai.needsFunding.value = false
+      await ai.sendMessage('test')
+      expect(ai.needsFunding.value).toBe(true); expect(ai.needsApiKey.value).toBe(false)
+      expect(store.messages.find(m => m.role === 'assistant')?.content).toContain('spending allowance')
+    })
+
     it('handles connection errors gracefully', async () => {
       globalThis.fetch = vi.fn().mockRejectedValue(new Error('Network failure'))
 

aiui/packages/app/src/components/chat/ChatHeader.vue

@@ -123,6 +123,7 @@
           :style="modelPickerDropdownStyle"
           @click.stop
         >
+        <button v-if="archyBridge.isInArchy()" class="w-full text-left rounded-lg px-3 py-2 text-sm text-white/90 hover:bg-white/10" @click="showModelPicker = false; archyBridge.requestAISetup()">AI connection</button>
         <div v-for="provider in availableProviders" :key="provider.id">
           <p class="text-xs font-semibold uppercase tracking-wider mb-1.5 px-1 text-white/40">
             {{ provider.name }}
@@ -247,6 +248,7 @@ import { useAI } from '@/composables/useAI'
 import { useContentPanel } from '@/composables/useContentPanel'
 import { downloadConversation, type ExportFormat } from '@/utils/conversation-export'
 import { parseImportFile } from '@/utils/conversation-import'
+import { archyBridge } from '@/services/archyBridge'
 import { useComparisonMode } from '@/composables/useComparisonMode'
 
 defineProps<{
@@ -332,8 +334,7 @@ const modelDisplayName = computed(() => {
 })
 
 function selectModel(providerId: string, modelId: string) {
-  setProvider(providerId as 'routstr' | 'claude' | 'openrouter' | 'mock')
-  setModel(modelId)
+  if (setProvider(providerId as Parameters<typeof setProvider>[0])) setModel(modelId)
   showModelPicker.value = false
 }
 

aiui/packages/app/src/components/chat/ChatWindow.vue

@@ -186,8 +186,9 @@ defineEmits<{
 }>()
 
 const chatStore = useChatStore()
-const { sendMessage, stopGeneration, editAndResend, regenerateLastResponse, activeModel, needsApiKey } = useAI()
+const { sendMessage, stopGeneration, editAndResend, regenerateLastResponse, activeModel, needsApiKey, needsFunding } = useAI()
 const { updatePanelFromText, panelOpen, panelFilms, panelTitle, activeTab, availableTabs, setActiveTab, enterDesignSystemMode } = useContentPanel()
+import { archyBridge } from '@/services/archyBridge'
 import { useCodeContext } from '@/composables/useCodeContext'
 import { useVisualViewport } from '@/composables/useVisualViewport'
 const codeContext = useCodeContext()
@@ -206,11 +207,19 @@ const showSettings = ref(false)
 // without fixing anything).
 watch(needsApiKey, (needs) => {
   if (needs) {
-    showSettings.value = true
+    if (archyBridge.isInArchy()) archyBridge.requestAISetup()
+    else showSettings.value = true
     needsApiKey.value = false
   }
 })
 
+watch(needsFunding, needed => {
+  if (!needed) return
+  if (archyBridge.isInArchy()) archyBridge.requestAISetup('funding')
+  else showSettings.value = true
+  needsFunding.value = false
+})
+
 // Scroll position memory per conversation
 const scrollPositions = new Map<string, number>()
 

aiui/packages/app/src/components/settings/ApiKeyManager.vue

@@ -1,5 +1,9 @@
 <template>
-  <div class="space-y-4">
+  <div v-if="embedded" class="space-y-3">
+    <p class="text-sm">AI connections and private keys are managed by this node.</p>
+    <button class="rounded-lg px-3 py-2 bg-white/10 text-sm" @click="archyBridge.requestAISetup()">Manage AI connection</button>
+  </div>
+  <div v-else class="space-y-4">
     <h3 class="text-sm font-bold" :class="isDark ? 'text-white/90' : 'text-gray-900'">
       API Keys
     </h3>
@@ -93,10 +97,12 @@
 </template>
 
 <script setup lang="ts">
+import { archyBridge } from '@/services/archyBridge'
 import { ref, onMounted } from 'vue'
 import { useTheme } from '@/composables/useTheme'
 import { storeApiKey, getApiKey, deleteApiKey, listProviders, maskApiKey } from '@/utils/key-vault'
 
+const embedded = archyBridge.isInArchy()
 const { isDark } = useTheme()
 
 interface ProviderInfo {
@@ -156,5 +162,5 @@ async function removeKey(provider: string) {
   await loadProviders()
 }
 
-onMounted(loadProviders)
+onMounted(() => { if (!embedded) void loadProviders() })
 </script>

aiui/packages/app/src/composables/useAI.ts

@@ -13,7 +13,7 @@ import { useCodeContext } from '@/composables/useCodeContext'
 import { apiFetch } from '@/utils/api-fetch'
 import { useSettingsStore } from '@/stores/settings'
 
-type Provider = 'routstr' | 'claude' | 'openrouter' | 'mock'
+type Provider = 'routstr' | 'claude' | 'openrouter' | 'mock' | 'openai' | 'auto' | 'local'
 
 // API paths are relative to the base URL so they work both in dev (/) and Archy (/aiui/)
 const BASE = import.meta.env.BASE_URL || '/'
@@ -120,34 +120,15 @@ Prioritize Podcasting 2.0–friendly platforms: Fountain.fm, Podcast Index, Cast
 Always include these tags so the UI can render rich cards. Write a brief reason why each is worth checking out.
 ${librarySection}`
 
-const activeProvider = ref<Provider>('claude')
+const activeProvider = ref<Provider>(archyBridge.isInArchy() ? 'auto' : 'claude')
 
 const activeModel = ref('claude-haiku-4.5')
 
-// One-shot signal a send/regenerate/edit failure looked like a missing or
-// invalid API key (or an unreachable proxy) rather than a transient/server
-// error — consumed by ChatWindow.vue to auto-open Settings so the user isn't
-// left in a dead end with no obvious next step. Deliberately narrow (401/403,
-// explicit "api key"/"unauthorized" text, or a connection-level failure to
-// reach the proxy at all) so a rate-limited or momentarily-flaky provider
-// response does NOT send the user to Settings for a problem Settings can't
-// fix. Reset to false by the consumer immediately after acting on it, so it
-// behaves as a pulse rather than sticky state (each new failure can re-fire).
+// Credentials require setup; network failures and provider outages require retry.
 const needsApiKey = ref(false)
-
+const needsFunding = ref(false)
 function looksLikeMissingApiKey(err: string): boolean {
-  const lower = err.toLowerCase()
-  return (
-    /\b(401|403)\b/.test(err) ||
-    lower.includes('api key') ||
-    lower.includes('x-api-key') ||
-    lower.includes('unauthorized') ||
-    lower.includes('authentication_error') ||
-    lower.includes('failed to fetch') ||
-    lower.includes('econnrefused') ||
-    lower.includes(' 502') ||
-    lower.includes(' 503')
-  )
+  return /\b(401|403)\b|api[ _-]?key|unauthorized|authentication_error|credential/i.test(err)
 }
 
 // ─── Routstr model catalog (fetched from the node's session-gated proxy) ───
@@ -161,7 +142,7 @@ async function refreshRoutstrModels() {
   routstrModelsFetched = true
   try {
     const res = await apiFetch(ROUTSTR_MODELS_PATH)
-    if (!res.ok) return
+    if (!res.ok) { routstrModelsFetched = false; return }
     const data = await res.json()
     if (Array.isArray(data?.data)) {
       routstrModels.value = data.data
@@ -170,13 +151,21 @@ async function refreshRoutstrModels() {
           id: m.id as string,
           name: (m.name as string) || (m.id as string),
         }))
-    }
+      if (activeProvider.value === 'routstr' && activeModel.value === 'routstr-unavailable' && routstrModels.value[0]) activeModel.value = routstrModels.value[0].id
+    } else { routstrModelsFetched = false }
   } catch {
     routstrModelsFetched = false // allow a retry on the next send/open
   }
 }
 
 const availableProviders = computed(() => {
+  if (archyBridge.isInArchy()) return [
+    { id: 'local' as Provider, name: 'Local AI', models: [{ id: 'node', name: 'Node configuration' }] },
+    { id: 'auto' as Provider, name: 'Node AI', models: [{ id: 'node', name: 'Node configuration' }] },
+    { id: 'claude' as Provider, name: 'Claude API', models: [{ id: 'node', name: 'Node configuration' }] },
+    { id: 'openai' as Provider, name: 'OpenAI API', models: [{ id: activeProvider.value === 'openai' ? activeModel.value : 'node', name: activeProvider.value === 'openai' ? activeModel.value : 'Configure model' }] },
+    { id: 'routstr' as Provider, name: 'Routstr (sats)', models: routstrModels.value.length ? routstrModels.value : [{ id: 'routstr-unavailable', name: 'Models unavailable — retry' }] },
+  ]
   const providers: { id: Provider; name: string; models: { id: string; name: string }[] }[] = [
     {
       id: 'routstr',
@@ -187,7 +176,7 @@ const availableProviders = computed(() => {
     },
     {
       id: 'claude',
-      name: 'Claude (Max)',
+      name: 'Claude API',
       models: [
         { id: 'claude-haiku-4.5', name: 'Claude 4.5 Haiku' },
         { id: 'claude-sonnet-4', name: 'Claude Sonnet 4' },
@@ -207,24 +196,36 @@ const availableProviders = computed(() => {
   })
   providers.push({
     id: 'mock',
-    name: 'Local (no API)',
+    name: 'Demo echo',
     models: [{ id: 'echo', name: 'Echo (mirror input)' }],
   })
   return providers
 })
 
 function setProvider(provider: Provider) {
+  if (archyBridge.isInArchy()) {
+    if (provider === 'routstr' && activeProvider.value === 'routstr') return true
+    archyBridge.requestAISetup(); return false
+  }
   activeProvider.value = provider
   const p = availableProviders.value.find((pp) => pp.id === provider)
   if (p && p.models.length > 0) {
     activeModel.value = p.models[0].id
   }
+  return true
 }
 
 function setModel(model: string) {
+  if (archyBridge.isInArchy() && activeProvider.value !== 'routstr') { archyBridge.requestAISetup(); return }
   activeModel.value = model
 }
 
+archyBridge.onProviderConfigured(({ provider, model }) => {
+  activeProvider.value = provider
+  activeModel.value = model || (provider === 'routstr' ? routstrModels.value[0]?.id || 'routstr-unavailable' : 'node')
+  if (provider === 'routstr') void refreshRoutstrModels()
+})
+
 interface ChatMessage {
   role: 'user' | 'assistant'
   content: string
@@ -448,6 +449,7 @@ async function streamRoutstr(
   })
 
   const bodyText = await res.text().catch(() => '')
+  if (res.status === 402) needsFunding.value = true
   if (!res.ok) {
     // The node's refusals carry a plain-language error.message (budget not
     // set, budget spent, wallet can't fund) — surface it verbatim.
@@ -974,5 +976,6 @@ export function useAI() {
     setProvider,
     setModel,
     needsApiKey,
+    needsFunding,
   }
 }

aiui/packages/app/src/services/archyBridge.ts

@@ -55,6 +55,10 @@ interface ThemeInfo {
 type PermissionsCallback = (categories: AIContextCategory[]) => void
 type ThemeCallback = (theme: ThemeInfo) => void
 
+export interface AIProviderSelection { provider: 'auto' | 'local' | 'claude' | 'openai' | 'routstr'; model: string }
+const providerCallbacks = new Set<(selection: AIProviderSelection) => void>()
+let currentProvider: AIProviderSelection | null = null
+
 let requestId = 0
 const pendingRequests = new Map<string, {
   resolve: (value: unknown) => void
@@ -80,12 +84,19 @@ function postToParent(msg: unknown) {
 
 function handleMessage(event: MessageEvent) {
   // Always validate origin — reject if not configured or mismatched
-  if (!allowedOrigin || event.origin !== allowedOrigin) return
+  if (!allowedOrigin || event.origin !== allowedOrigin || event.source !== window.parent) return
 
   const msg = event.data
   if (!msg || typeof msg.type !== 'string') return
 
   switch (msg.type) {
+    case 'ai:provider-configured': {
+      if (!['auto', 'local', 'claude', 'openai', 'routstr'].includes(msg.provider)) break
+      const selection = { provider: msg.provider as AIProviderSelection['provider'], model: typeof msg.model === 'string' ? msg.model : '' }
+      currentProvider = selection
+      for (const callback of providerCallbacks) callback(selection)
+      break
+    }
     case 'context:response': {
       const pending = pendingRequests.get(msg.id)
       if (pending) {
@@ -223,11 +234,21 @@ export const archyBridge = {
     }
   },
 
+  requestAISetup(reason?: 'funding') { postToParent({ type: 'ai:setup-request', ...(reason ? { reason } : {}) }) },
+
+  onProviderConfigured(callback: (selection: AIProviderSelection) => void) {
+    providerCallbacks.add(callback)
+    if (currentProvider) callback(currentProvider)
+    return () => { providerCallbacks.delete(callback) }
+  },
+
   /** Clean up listeners */
   destroy() {
     window.removeEventListener('message', handleMessage)
     pendingRequests.clear()
     initialized = false
+    currentProvider = null
+    allowedOrigin = null
   },
 
   /** Check if running inside Archy iframe */