@ulam/halohalo 0.3.0 → 0.3.2

package/README.md

@@ -1,20 +1,41 @@
 # @ulam/halohalo
 
-AI service adapters, model configuration, and provider abstraction. Vanilla core with a React hooks adapter.
+AI service adapters, model configuration, and provider abstraction. Vanilla core with React, Vue, and Angular adapters.
 
 Named for halo-halo, the Filipino shaved ice dessert: a mix of many things that somehow works together.
 
-## The ulam framework
+## Purpose & Scope
 
-```text
-ulam
-├── @ulam/halohalo     mixed  : AI provider adapters  ← you are here
-├── @ulam/taho         warm   : ARIA live region announcer
-├── @ulam/sili         hot    : focus management, overlays, routing
-├── @ulam/calamansi    sour   : i18n, hooks, utilities, logic
-├── @ulam/ube          sweet  : React UI components, theming
-└── @ulam/sawsawan     bridge : wires the above together
-```
+**What halohalo does:**
+
+- Provider abstraction for Anthropic, OpenAI, and Google
+- API key management (localStorage-backed, never sent to server)
+- Model selection and configuration per provider
+- Completion calls with consistent interface across providers
+- Tool calling and agentic mode for complex operations
+- Framework-agnostic vanilla core with framework adapters
+- Zero build-time provider detection or configuration
+
+**What halohalo doesn't do:**
+
+- Message history or conversation management (bring your own state)
+- Streaming response handling (returns complete results)
+- Rate limiting or retry logic (use middleware patterns for these)
+- Token counting or pricing calculation (external concerns)
+- API key validation or rotation (user responsibility)
+- Multi-user authentication or access control
+
+**Who should use halohalo:**
+
+- Apps that need multiple AI provider support with runtime switching
+- Projects storing API keys client-side (browser-only, no backend)
+- Vanilla JavaScript, React, Vue, or Angular apps using AI features
+- Applications wanting provider-agnostic completion calls
+- Teams integrating AI features without external API servers
+
+## The ulam Framework
+
+Halohalo is one of six independent packages in the ulam framework. See [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the complete framework structure and dependency graph.
 
 ## Install
 
@@ -188,6 +209,4 @@ export class SettingsComponent {
 | `@ulam/halohalo/vue` | `useCompletion`, `useProviderConfig` |
 | `@ulam/halohalo/angular` | `CompletionService`, `ProviderConfigService`, `provideHalohalo` |
 
-## License
-
-MIT
+See the [root README](../../README.md) for a complete framework support overview across all ulam packages.

package/agenticAiService.js

@@ -1,76 +1,76 @@
-import { callAnthropicWithTools } from './fetch.js'
-import { makeSearchTool } from './search.js'
-import { getAdapter } from '@ulam/sawsawan'
-import { AI_AGENTIC_MAX_TOKENS, AGENTIC_MAX_TOOL_TURNS, LS_APIKEY_PREFIX } from './constants.js'
-import { getAiModel } from './prefs.js'
-import { parseAiResponse } from './aiService.js'
-import { getSystemPrompt } from './init.js'
-
-export { AiApiError } from './providers.js'
-
-const FALLBACK_SYSTEM_PROMPT = `You are an AI assistant helping rewrite text entries based on user notes. Search for related entries before rewriting, then produce a revised description and suggested fix.
-
-Format your final output as exactly two lines:
-Description: [rewritten description]
-Suggested Fix: [rewritten suggested fix]`
-
-const CORPUS_SEARCH_FIELDS = [
-  { name: 'title',    weight: 0.32 },
-  { name: 'keywords', weight: 0.30 },
-  { name: 'desc',     weight: 0.07 },
-  { name: 'fix',      weight: 0.03 },
-]
-
-const CORPUS_PICK = ['id', 'title', 'primarySC', 'severity', 'desc', 'fix']
-
-export async function getAgenticRefinement({ finding, descText, fixText, note, corpus }) {
-  const key = await getAdapter().getKey(`${LS_APIKEY_PREFIX}anthropic`)
-
-  if (!key) throw new Error('Anthropic API key required for agentic mode. Add one in Settings → AI Assist.')
-
-  const model = getAiModel('anthropic')
-
-  const { schema: toolSchema, handler: toolHandler } = makeSearchTool(corpus, {
-    name: 'search_corpus',
-    description:
-      'Search the accessibility finding corpus for entries related to a natural-language query. ' +
-      'Call this before rewriting to find similar findings that demonstrate the expected voice, ' +
-      'tone, and technical depth. Returns up to 3 matching entries.',
-    queryDescription: 'Natural-language search query, e.g. "keyboard focus visible" or "color contrast low vision".',
-    fields: CORPUS_SEARCH_FIELDS,
-    pick: CORPUS_PICK,
-    limit: 3,
-  })
-
-  const userPrompt = `Refine this accessibility finding based on the auditor's note.
-
-Title: ${finding.title}
-WCAG SC: ${finding.primarySC}
-Severity: ${finding.severity}
-Platform: ${finding.platform}
-
-Current description:
-${descText}
-
-Current suggested fix:
-${fixText}
-
-Auditor's note: "${note}"
-
-Search the corpus for related findings, then rewrite the description and suggested fix to reflect the refinement.`
-
-  const messages = [{ role: 'user', content: userPrompt }]
-
-  const text = await callAnthropicWithTools({
-    key,
-    model,
-    system: getSystemPrompt() || FALLBACK_SYSTEM_PROMPT,
-    tools: [toolSchema],
-    messages,
-    maxTokens: AI_AGENTIC_MAX_TOKENS,
-    maxTurns: AGENTIC_MAX_TOOL_TURNS,
-    onToolCall: toolHandler,
-  })
-
-  return parseAiResponse(text)
-}
+import { callAnthropicWithTools } from './fetch.js'
+import { makeSearchTool } from './search.js'
+import { AI_AGENTIC_MAX_TOKENS, AGENTIC_MAX_TOOL_TURNS, LS_APIKEY_PREFIX } from './constants.js'
+import { getAiModel } from './prefs.js'
+import { parseAiResponse } from './aiService.js'
+import { getSystemPrompt } from './init.js'
+
+export { AiApiError } from './providers.js'
+
+const FALLBACK_SYSTEM_PROMPT = `You are an AI assistant helping rewrite text entries based on user notes. Search for related entries before rewriting, then produce a revised description and suggested fix.
+
+Format your final output as exactly two lines:
+Description: [rewritten description]
+Suggested Fix: [rewritten suggested fix]`
+
+const CORPUS_SEARCH_FIELDS = [
+  { name: 'title',    weight: 0.32 },
+  { name: 'keywords', weight: 0.30 },
+  { name: 'desc',     weight: 0.07 },
+  { name: 'fix',      weight: 0.03 },
+]
+
+const CORPUS_PICK = ['id', 'title', 'primarySC', 'severity', 'desc', 'fix']
+
+export async function getAgenticRefinement({ finding, descText, fixText, note, corpus }) {
+  const { getAdapter } = await import('@ulam/sawsawan')
+  const key = await getAdapter().getKey(`${LS_APIKEY_PREFIX}anthropic`)
+
+  if (!key) throw new Error('Anthropic API key required for agentic mode. Add one in Settings → AI Assist.')
+
+  const model = getAiModel('anthropic')
+
+  const { schema: toolSchema, handler: toolHandler } = makeSearchTool(corpus, {
+    name: 'search_corpus',
+    description:
+      'Search the accessibility finding corpus for entries related to a natural-language query. ' +
+      'Call this before rewriting to find similar findings that demonstrate the expected voice, ' +
+      'tone, and technical depth. Returns up to 3 matching entries.',
+    queryDescription: 'Natural-language search query, e.g. "keyboard focus visible" or "color contrast low vision".',
+    fields: CORPUS_SEARCH_FIELDS,
+    pick: CORPUS_PICK,
+    limit: 3,
+  })
+
+  const userPrompt = `Refine this accessibility finding based on the auditor's note.
+
+Title: ${finding.title}
+WCAG SC: ${finding.primarySC}
+Severity: ${finding.severity}
+Platform: ${finding.platform}
+
+Current description:
+${descText}
+
+Current suggested fix:
+${fixText}
+
+Auditor's note: "${note}"
+
+Search the corpus for related findings, then rewrite the description and suggested fix to reflect the refinement.`
+
+  const messages = [{ role: 'user', content: userPrompt }]
+
+  const text = await callAnthropicWithTools({
+    key,
+    model,
+    system: getSystemPrompt() || FALLBACK_SYSTEM_PROMPT,
+    tools: [toolSchema],
+    messages,
+    maxTokens: AI_AGENTIC_MAX_TOKENS,
+    maxTurns: AGENTIC_MAX_TOOL_TURNS,
+    onToolCall: toolHandler,
+  })
+
+  return parseAiResponse(text)
+}

package/aiService.js

@@ -1,31 +1,31 @@
-import { callProvider } from './fetch.js'
-import { getAdapter } from '@ulam/sawsawan'
-import { AI_MAX_TOKENS, AI_DESC_REGEX, AI_FIX_REGEX, LS_APIKEY_PREFIX } from './constants.js'
-import { getAiProvider, getAiModel } from './prefs.js'
-import { getBuildPrompt } from './init.js'
-
-export { AiApiError, httpStatusToErrorType } from './providers.js'
-
-export function parseAiResponse(text) {
-  const descMatch = text.match(AI_DESC_REGEX)
-  const fixMatch  = text.match(AI_FIX_REGEX)
-  return {
-    desc: descMatch?.[1]?.trim() || null,
-    fix:  fixMatch?.[1]?.trim()  || null,
-  }
-}
-
-export async function getAiRefinement({ finding, descText, fixText, note }) {
-  const buildPrompt = getBuildPrompt()
-  if (!buildPrompt) throw new Error('halohalo: call initHalohalo({ buildPrompt }) before getAiRefinement')
-
-  const provider = getAiProvider()
-  const key = await getAdapter().getKey(`${LS_APIKEY_PREFIX}${provider}`)
-
-  if (!key) throw new Error(`No API key found for ${provider}. Add one in Settings.`)
-
-  const model = getAiModel(provider)
-  const prompt = buildPrompt({ finding, descText, fixText, note })
-  const text = await callProvider({ provider, model, key, prompt, maxTokens: AI_MAX_TOKENS })
-  return parseAiResponse(text)
-}
+import { callProvider } from './fetch.js'
+import { AI_MAX_TOKENS, AI_DESC_REGEX, AI_FIX_REGEX, LS_APIKEY_PREFIX } from './constants.js'
+import { getAiProvider, getAiModel } from './prefs.js'
+import { getBuildPrompt } from './init.js'
+
+export { AiApiError, httpStatusToErrorType } from './providers.js'
+
+export function parseAiResponse(text) {
+  const descMatch = text.match(AI_DESC_REGEX)
+  const fixMatch  = text.match(AI_FIX_REGEX)
+  return {
+    desc: descMatch?.[1]?.trim() || null,
+    fix:  fixMatch?.[1]?.trim()  || null,
+  }
+}
+
+export async function getAiRefinement({ finding, descText, fixText, note }) {
+  const buildPrompt = getBuildPrompt()
+  if (!buildPrompt) throw new Error('halohalo: call initHalohalo({ buildPrompt }) before getAiRefinement')
+
+  const provider = getAiProvider()
+  const { getAdapter } = await import('@ulam/sawsawan')
+  const key = await getAdapter().getKey(`${LS_APIKEY_PREFIX}${provider}`)
+
+  if (!key) throw new Error(`No API key found for ${provider}. Add one in Settings.`)
+
+  const model = getAiModel(provider)
+  const prompt = buildPrompt({ finding, descText, fixText, note })
+  const text = await callProvider({ provider, model, key, prompt, maxTokens: AI_MAX_TOKENS })
+  return parseAiResponse(text)
+}

package/connectivity.js

@@ -1,17 +1,17 @@
-/**
- * Probes a list of endpoints in parallel to check network reachability.
- *
- * @param {Array<{ label: string, url: string }>} probes
- * @param {number} [timeoutMs=4000]
- * @returns {Promise<Array<{ label: string, ok: boolean }>>}
- */
-export async function checkConnectivity(probes, timeoutMs = 4000) {
-  const results = await Promise.allSettled(
-    probes.map(p =>
-      fetch(p.url, { method: 'HEAD', mode: 'no-cors', signal: AbortSignal.timeout(timeoutMs) })
-        .then(() => ({ label: p.label, ok: true }))
-        .catch(() => ({ label: p.label, ok: false }))
-    )
-  )
-  return results.map(r => r.value || r.reason)
-}
+/**
+ * Probes a list of endpoints in parallel to check network reachability.
+ *
+ * @param {Array<{ label: string, url: string }>} probes
+ * @param {number} [timeoutMs=4000]
+ * @returns {Promise<Array<{ label: string, ok: boolean }>>}
+ */
+export async function checkConnectivity(probes, timeoutMs = 4000) {
+  const results = await Promise.allSettled(
+    probes.map(p =>
+      fetch(p.url, { method: 'HEAD', mode: 'no-cors', signal: AbortSignal.timeout(timeoutMs) })
+        .then(() => ({ label: p.label, ok: true }))
+        .catch(() => ({ label: p.label, ok: false }))
+    )
+  )
+  return results.map(r => r.value || r.reason)
+}

package/createCompletion.js

@@ -1,113 +1,113 @@
-import { callProvider, callAnthropicWithTools } from './fetch.js'
-import { AiApiError } from './providers.js'
-
-const DEFAULT_TYPEWRITER = { tickMs: 33, minCharsPerTick: 2, charDivisor: 40 }
-
-/**
- * Vanilla completion runner. No React required.
- * Returns { complete(options), cancel() } plus a subscribe() for state changes.
- *
- * State: { loading: boolean, animating: boolean }
- *
- * options for complete():
- *   provider, model, key, prompt, maxTokens: for standard completions
- *   agentOptions: { system, tools, messages, maxTurns, onToolCall }: for agentic
- *   onResult(fields)       : called with parsed result after completion
- *   onError(error)         : called with AiApiError on failure
- *   parseResponse(text)    : maps raw text to result fields object
- *   typewriter             : { tickMs, minCharsPerTick, charDivisor } or false
- *   onAnimate(field, text) : called each tick with field + current text slice
- *   onAnimateDone()        : called when typewriter finishes
- */
-export function createCompletion() {
-  let loading = false
-  let animating = false
-  let timer = null
-  const listeners = new Set()
-  const notify = () => listeners.forEach(fn => fn({ loading, animating }))
-
-  function runTypewriter(fields, { typewriter, onAnimate, onAnimateDone }) {
-    clearTimeout(timer)
-    const { tickMs, minCharsPerTick, charDivisor } = { ...DEFAULT_TYPEWRITER, ...typewriter }
-
-    const entries = Object.entries(fields).filter(([, v]) => typeof v === 'string' && v.length > 0)
-    if (!entries.length) {
-      animating = false
-      notify()
-      onAnimateDone?.()
-      return
-    }
-
-    const total = entries.reduce((sum, [, v]) => sum + v.length, 0)
-    const charsPerTick = Math.max(minCharsPerTick, Math.ceil(total / charDivisor))
-    const indices = Object.fromEntries(entries.map(([k]) => [k, 0]))
-    let entryIdx = 0
-
-    function tick() {
-      const [field, text] = entries[entryIdx]
-      indices[field] = Math.min(indices[field] + charsPerTick, text.length)
-      onAnimate?.(field, text.slice(0, indices[field]))
-      if (indices[field] >= text.length) entryIdx++
-      if (entryIdx >= entries.length) {
-        animating = false
-        notify()
-        onAnimateDone?.()
-      } else {
-        timer = setTimeout(tick, tickMs)
-      }
-    }
-
-    timer = setTimeout(tick, tickMs)
-  }
-
-  return {
-    get loading() { return loading },
-    get animating() { return animating },
-
-    subscribe(fn) {
-      listeners.add(fn)
-      return () => listeners.delete(fn)
-    },
-
-    async complete({ provider, model, key, prompt, maxTokens, agentOptions, onResult, onError, parseResponse, typewriter = DEFAULT_TYPEWRITER, onAnimate, onAnimateDone }) {
-      loading = true
-      notify()
-
-      try {
-        let text
-        if (agentOptions) {
-          const { system, tools, messages, maxTurns, onToolCall } = agentOptions
-          text = await callAnthropicWithTools({ key, model, system, tools, messages, maxTokens, maxTurns, onToolCall })
-        } else {
-          text = await callProvider({ provider, model, key, prompt, maxTokens })
-        }
-
-        const result = parseResponse ? parseResponse(text) : { text }
-        loading = false
-
-        if (typewriter && onAnimate) {
-          animating = true
-          notify()
-          onResult?.(result)
-          runTypewriter(result, { typewriter, onAnimate, onAnimateDone })
-        } else {
-          notify()
-          onResult?.(result)
-          onAnimateDone?.()
-        }
-      } catch (e) {
-        loading = false
-        animating = false
-        notify()
-        onError?.(e instanceof AiApiError ? e : new AiApiError('api_error'))
-      }
-    },
-
-    cancel() {
-      clearTimeout(timer)
-      loading = false
-      animating = false
-      notify()
-    },
-  }
-}
+import { callProvider, callAnthropicWithTools } from './fetch.js'
+import { AiApiError } from './providers.js'
+
+const DEFAULT_TYPEWRITER = { tickMs: 33, minCharsPerTick: 2, charDivisor: 40 }
+
+/**
+ * Vanilla completion runner. No React required.
+ * Returns { complete(options), cancel() } plus a subscribe() for state changes.
+ *
+ * State: { loading: boolean, animating: boolean }
+ *
+ * options for complete():
+ *   provider, model, key, prompt, maxTokens: for standard completions
+ *   agentOptions: { system, tools, messages, maxTurns, onToolCall }: for agentic
+ *   onResult(fields)       : called with parsed result after completion
+ *   onError(error)         : called with AiApiError on failure
+ *   parseResponse(text)    : maps raw text to result fields object
+ *   typewriter             : { tickMs, minCharsPerTick, charDivisor } or false
+ *   onAnimate(field, text) : called each tick with field + current text slice
+ *   onAnimateDone()        : called when typewriter finishes
+ */
+export function createCompletion() {
+  let loading = false
+  let animating = false
+  let timer = null
+  const listeners = new Set()
+  const notify = () => listeners.forEach(fn => fn({ loading, animating }))
+
+  function runTypewriter(fields, { typewriter, onAnimate, onAnimateDone }) {
+    clearTimeout(timer)
+    const { tickMs, minCharsPerTick, charDivisor } = { ...DEFAULT_TYPEWRITER, ...typewriter }
+
+    const entries = Object.entries(fields).filter(([, v]) => typeof v === 'string' && v.length > 0)
+    if (!entries.length) {
+      animating = false
+      notify()
+      onAnimateDone?.()
+      return
+    }
+
+    const total = entries.reduce((sum, [, v]) => sum + v.length, 0)
+    const charsPerTick = Math.max(minCharsPerTick, Math.ceil(total / charDivisor))
+    const indices = Object.fromEntries(entries.map(([k]) => [k, 0]))
+    let entryIdx = 0
+
+    function tick() {
+      const [field, text] = entries[entryIdx]
+      indices[field] = Math.min(indices[field] + charsPerTick, text.length)
+      onAnimate?.(field, text.slice(0, indices[field]))
+      if (indices[field] >= text.length) entryIdx++
+      if (entryIdx >= entries.length) {
+        animating = false
+        notify()
+        onAnimateDone?.()
+      } else {
+        timer = setTimeout(tick, tickMs)
+      }
+    }
+
+    timer = setTimeout(tick, tickMs)
+  }
+
+  return {
+    get loading() { return loading },
+    get animating() { return animating },
+
+    subscribe(fn) {
+      listeners.add(fn)
+      return () => listeners.delete(fn)
+    },
+
+    async complete({ provider, model, key, prompt, maxTokens, agentOptions, onResult, onError, parseResponse, typewriter = DEFAULT_TYPEWRITER, onAnimate, onAnimateDone }) {
+      loading = true
+      notify()
+
+      try {
+        let text
+        if (agentOptions) {
+          const { system, tools, messages, maxTurns, onToolCall } = agentOptions
+          text = await callAnthropicWithTools({ key, model, system, tools, messages, maxTokens, maxTurns, onToolCall })
+        } else {
+          text = await callProvider({ provider, model, key, prompt, maxTokens })
+        }
+
+        const result = parseResponse ? parseResponse(text) : { text }
+        loading = false
+
+        if (typewriter && onAnimate) {
+          animating = true
+          notify()
+          onResult?.(result)
+          runTypewriter(result, { typewriter, onAnimate, onAnimateDone })
+        } else {
+          notify()
+          onResult?.(result)
+          onAnimateDone?.()
+        }
+      } catch (e) {
+        loading = false
+        animating = false
+        notify()
+        onError?.(e instanceof AiApiError ? e : new AiApiError('api_error'))
+      }
+    },
+
+    cancel() {
+      clearTimeout(timer)
+      loading = false
+      animating = false
+      notify()
+    },
+  }
+}

package/createProviderConfig.js

@@ -1,80 +1,85 @@
-import { DEFAULT_MODELS, DEFAULT_PROVIDERS, DEFAULT_PROVIDER_LABELS } from './providers.js'
-import { getAdapter } from '@ulam/sawsawan'
-
-/**
- * Vanilla provider config store. No React required.
- * Returns a plain object with getters, setters, and a subscribe() for change notifications.
- *
- * storageKeys: { provider, modelPrefix, keyPrefix, mode? }
- * providers: optional array of { id, label, defaultModel? }
- */
-export function createProviderConfig(storageKeys, providers = DEFAULT_PROVIDERS) {
-  const { provider: providerKey, modelPrefix, keyPrefix, mode: modeKey } = storageKeys
-
-  const providerList = providers.map(p =>
-    typeof p === 'string' ? { id: p, label: DEFAULT_PROVIDER_LABELS[p] || p } : p
-  )
-
-  let provider = getAdapter().readPref(providerKey) || providerList[0]?.id || 'anthropic'
-
-  let models = Object.fromEntries(
-    providerList.map(p => [
-      p.id,
-      getAdapter().readPref(`${modelPrefix}${p.id}`) || p.defaultModel || DEFAULT_MODELS[p.id] || '',
-    ])
-  )
-
-  let mode = modeKey ? getAdapter().readPref(modeKey) === 'true' : false
-
-  const listeners = new Set()
-  const notify = () => listeners.forEach(fn => fn())
-
-  return {
-    get provider() { return provider },
-    get models() { return { ...models } },
-    get mode() { return mode },
-    get providers() { return providerList },
-
-    setProvider(id) {
-      getAdapter().writePref(providerKey, id)
-      provider = id
-      notify()
-    },
-
-    setModel(providerId, modelId) {
-      getAdapter().writePref(`${modelPrefix}${providerId}`, modelId)
-      models = { ...models, [providerId]: modelId }
-      notify()
-    },
-
-    setMode(value) {
-      if (!modeKey) return
-      getAdapter().writePref(modeKey, value ? 'true' : 'false')
-      mode = value
-      notify()
-    },
-
-    async setKey(providerId, value) {
-      await getAdapter().setKey(`${keyPrefix}${providerId}`, value)
-    },
-
-    async getKey(providerId) {
-      return (await getAdapter().getKey(`${keyPrefix}${providerId}`)) || ''
-    },
-
-    getModel(providerId) {
-      return models[providerId] || DEFAULT_MODELS[providerId] || ''
-    },
-
-    getLabel(providerId) {
-      return providerList.find(p => p.id === providerId)?.label
-        || DEFAULT_PROVIDER_LABELS[providerId]
-        || providerId
-    },
-
-    subscribe(fn) {
-      listeners.add(fn)
-      return () => listeners.delete(fn)
-    },
-  }
-}
+import { DEFAULT_MODELS, DEFAULT_PROVIDERS, DEFAULT_PROVIDER_LABELS } from './providers.js'
+
+async function getAdapter() {
+  const mod = await import('@ulam/sawsawan')
+  return mod.getAdapter()
+}
+
+/**
+ * Vanilla provider config store. No React required.
+ * Returns a plain object with getters, setters, and a subscribe() for change notifications.
+ *
+ * storageKeys: { provider, modelPrefix, keyPrefix, mode? }
+ * providers: optional array of { id, label, defaultModel? }
+ */
+export async function createProviderConfig(storageKeys, providers = DEFAULT_PROVIDERS) {
+  const { provider: providerKey, modelPrefix, keyPrefix, mode: modeKey } = storageKeys
+  const adapter = await getAdapter()
+
+  const providerList = providers.map(p =>
+    typeof p === 'string' ? { id: p, label: DEFAULT_PROVIDER_LABELS[p] || p } : p
+  )
+
+  let provider = adapter.readPref(providerKey) || providerList[0]?.id || 'anthropic'
+
+  let models = Object.fromEntries(
+    providerList.map(p => [
+      p.id,
+      adapter.readPref(`${modelPrefix}${p.id}`) || p.defaultModel || DEFAULT_MODELS[p.id] || '',
+    ])
+  )
+
+  let mode = modeKey ? adapter.readPref(modeKey) === 'true' : false
+
+  const listeners = new Set()
+  const notify = () => listeners.forEach(fn => fn())
+
+  return {
+    get provider() { return provider },
+    get models() { return { ...models } },
+    get mode() { return mode },
+    get providers() { return providerList },
+
+    setProvider(id) {
+      adapter.writePref(providerKey, id)
+      provider = id
+      notify()
+    },
+
+    setModel(providerId, modelId) {
+      adapter.writePref(`${modelPrefix}${providerId}`, modelId)
+      models = { ...models, [providerId]: modelId }
+      notify()
+    },
+
+    setMode(value) {
+      if (!modeKey) return
+      adapter.writePref(modeKey, value ? 'true' : 'false')
+      mode = value
+      notify()
+    },
+
+    async setKey(providerId, value) {
+      await adapter.setKey(`${keyPrefix}${providerId}`, value)
+    },
+
+    async getKey(providerId) {
+      return (await adapter.getKey(`${keyPrefix}${providerId}`)) || ''
+    },
+
+    getModel(providerId) {
+      return models[providerId] || DEFAULT_MODELS[providerId] || ''
+    },
+
+    getLabel(providerId) {
+      return providerList.find(p => p.id === providerId)?.label
+        || DEFAULT_PROVIDER_LABELS[providerId]
+        || providerId
+    },
+
+    subscribe(fn) {
+      listeners.add(fn)
+      return () => listeners.delete(fn)
+    },
+  }
+}

package/fetch.js

@@ -1,113 +1,134 @@
-import { AiApiError, httpStatusToErrorType, PROVIDER_CONFIGS } from './providers.js'
-
-// ─── callProvider ─────────────────────────────────────────────────────────────
-// Single-turn completion against any configured provider.
-// Returns the response text string.
-
-export async function callProvider({ provider, model, key, prompt, maxTokens = 1024 }) {
-  const config = PROVIDER_CONFIGS[provider]
-  if (!config) throw new AiApiError('api_error', { provider })
-
-  let url
-  if (config.buildUrl) {
-    url = config.buildUrl(key, model)
-    if (!url) throw new AiApiError('api_error', { provider })
-  } else {
-    url = config.url
-  }
-
-  let res
-  try {
-    res = await fetch(url, {
-      method: 'POST',
-      headers: config.buildHeaders(key),
-      body: config.buildBody(prompt, model, maxTokens),
-    })
-  } catch {
-    throw new AiApiError('network_error', { provider })
-  }
-
-  if (!res.ok) {
-    throw new AiApiError(httpStatusToErrorType(res.status), { status: res.status, provider })
-  }
-
-  return config.parseResponse(res)
-}
-
-// ─── callAnthropicWithTools ───────────────────────────────────────────────────
-// Agentic tool-use loop for Anthropic. Calls the messages API repeatedly until
-// stop_reason is 'end_turn' or maxTurns is exhausted.
-//
-// onToolCall(toolName, toolInput) => toolResultContent (string or object)
-// Returns the final text block content.
-
-export async function callAnthropicWithTools({
-  key,
-  model,
-  system,
-  tools,
-  messages,
-  maxTokens = 2048,
-  maxTurns = 5,
-  onToolCall,
-}) {
-  const config = PROVIDER_CONFIGS.anthropic
-  let turns = 0
-
-  while (turns <= maxTurns) {
-    let res
-    try {
-      res = await fetch(config.url, {
-        method: 'POST',
-        headers: config.buildHeaders(key),
-        body: JSON.stringify({ model, max_tokens: maxTokens, system, tools, messages }),
-      })
-    } catch {
-      throw new AiApiError('network_error', { provider: 'anthropic' })
-    }
-
-    if (!res.ok) {
-      throw new AiApiError(httpStatusToErrorType(res.status), { status: res.status, provider: 'anthropic' })
-    }
-
-    const data = await res.json()
-
-    if (import.meta.env.DEV) console.log(`[halohalo] turn ${turns + 1}, stop_reason: ${data.stop_reason}`)
-
-    messages.push({ role: 'assistant', content: data.content })
-
-    if (data.stop_reason === 'end_turn') {
-      return data.content.find(b => b.type === 'text')?.text || ''
-    }
-
-    if (data.stop_reason === 'tool_use') {
-      if (turns >= maxTurns) {
-        if (import.meta.env.DEV) console.warn('[halohalo] maxTurns reached')
-        throw new AiApiError('api_error', { provider: 'anthropic' })
-      }
-
-      const toolBlocks = data.content.filter(b => b.type === 'tool_use')
-      const toolResults = await Promise.all(
-        toolBlocks.map(async (block) => {
-          const result = await onToolCall?.(block.name, block.input) ?? ''
-          if (import.meta.env.DEV) {
-            console.log(`[halohalo] tool_use: ${block.name}`, block.input, '→', result)
-          }
-          return {
-            type: 'tool_result',
-            tool_use_id: block.id,
-            content: typeof result === 'string' ? result : JSON.stringify(result),
-          }
-        })
-      )
-
-      messages.push({ role: 'user', content: toolResults })
-      turns++
-      continue
-    }
-
-    break
-  }
-
-  throw new AiApiError('api_error', { provider: 'anthropic' })
-}
+import { AiApiError, httpStatusToErrorType, PROVIDER_CONFIGS } from './providers.js'
+
+// ─── Provider URL Whitelist ───────────────────────────────────────────────────
+// Prevents SSRF attacks from user-configured provider URLs.
+const ALLOWED_PROVIDER_HOSTS = new Set([
+  'api.anthropic.com',
+  'api.openai.com',
+  'generativelanguage.googleapis.com',
+])
+
+function validateProviderUrl(url) {
+  try {
+    const hostname = new URL(url).hostname
+    return ALLOWED_PROVIDER_HOSTS.has(hostname)
+  } catch {
+    return false
+  }
+}
+
+// ─── callProvider ─────────────────────────────────────────────────────────────
+// Single-turn completion against any configured provider.
+// Returns the response text string.
+
+export async function callProvider({ provider, model, key, prompt, maxTokens = 1024 }) {
+  const config = PROVIDER_CONFIGS[provider]
+  if (!config) throw new AiApiError('api_error', { provider })
+
+  let url
+  if (config.buildUrl) {
+    url = config.buildUrl(key, model)
+    if (!url) throw new AiApiError('api_error', { provider })
+  } else {
+    url = config.url.replace('{model}', model)
+  }
+
+  if (!validateProviderUrl(url)) {
+    throw new AiApiError('api_error', { provider })
+  }
+
+  let res
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: config.buildHeaders(key),
+      body: config.buildBody(prompt, model, maxTokens),
+    })
+  } catch {
+    throw new AiApiError('network_error', { provider })
+  }
+
+  if (!res.ok) {
+    throw new AiApiError(httpStatusToErrorType(res.status), { status: res.status, provider })
+  }
+
+  return config.parseResponse(res)
+}
+
+// ─── callAnthropicWithTools ───────────────────────────────────────────────────
+// Agentic tool-use loop for Anthropic. Calls the messages API repeatedly until
+// stop_reason is 'end_turn' or maxTurns is exhausted.
+//
+// onToolCall(toolName, toolInput) => toolResultContent (string or object)
+// Returns the final text block content.
+
+export async function callAnthropicWithTools({
+  key,
+  model,
+  system,
+  tools,
+  messages,
+  maxTokens = 2048,
+  maxTurns = 5,
+  onToolCall,
+}) {
+  const config = PROVIDER_CONFIGS.anthropic
+  let turns = 0
+
+  while (turns <= maxTurns) {
+    let res
+    try {
+      res = await fetch(config.url, {
+        method: 'POST',
+        headers: config.buildHeaders(key),
+        body: JSON.stringify({ model, max_tokens: maxTokens, system, tools, messages }),
+      })
+    } catch {
+      throw new AiApiError('network_error', { provider: 'anthropic' })
+    }
+
+    if (!res.ok) {
+      throw new AiApiError(httpStatusToErrorType(res.status), { status: res.status, provider: 'anthropic' })
+    }
+
+    const data = await res.json()
+
+    if (import.meta.env.DEV) console.log(`[halohalo] turn ${turns + 1}, stop_reason: ${data.stop_reason}`)
+
+    messages.push({ role: 'assistant', content: data.content })
+
+    if (data.stop_reason === 'end_turn') {
+      return data.content.find(b => b.type === 'text')?.text || ''
+    }
+
+    if (data.stop_reason === 'tool_use') {
+      if (turns >= maxTurns) {
+        if (import.meta.env.DEV) console.warn('[halohalo] maxTurns reached')
+        throw new AiApiError('api_error', { provider: 'anthropic' })
+      }
+
+      const toolBlocks = data.content.filter(b => b.type === 'tool_use')
+      const toolResults = await Promise.all(
+        toolBlocks.map(async (block) => {
+          const result = await onToolCall?.(block.name, block.input) ?? ''
+          if (import.meta.env.DEV) {
+            console.log(`[halohalo] tool_use: ${block.name}`, block.input, '→', result)
+          }
+          return {
+            type: 'tool_result',
+            tool_use_id: block.id,
+            content: typeof result === 'string' ? result : JSON.stringify(result),
+          }
+        })
+      )
+
+      messages.push({ role: 'user', content: toolResults })
+      turns++
+      continue
+    }
+
+    break
+  }
+
+  throw new AiApiError('api_error', { provider: 'anthropic' })
+}

package/index.js

@@ -1,20 +1,20 @@
-// vanilla core
-export { initHalohalo } from './init.js'
-export { AiApiError, httpStatusToErrorType, PROVIDER_CONFIGS } from './providers.js'
-export { callProvider, callAnthropicWithTools } from './fetch.js'
-export { searchItems, makeSearchTool } from './search.js'
-export { createProviderConfig } from './createProviderConfig.js'
-export { createCompletion } from './createCompletion.js'
-export { getAiRefinement, parseAiResponse } from './aiService.js'
-export { getAgenticRefinement } from './agenticAiService.js'
-export { PROVIDERS, PROVIDER_MODELS, initModels, initApiKeys } from './models.js'
-export { getAiProvider, isAgenticModeEnabled, getAiModel, getProviderLabel } from './prefs.js'
-export { checkConnectivity } from './connectivity.js'
-export {
-  LS_AI_PROVIDER, LS_AGENTIC_MODE, LS_APIKEY_PREFIX, LS_AI_MODEL_PREFIX,
-  AI_MAX_TOKENS, AI_AGENTIC_MAX_TOKENS, AGENTIC_MAX_TOOL_TURNS,
-  AI_DESC_REGEX, AI_FIX_REGEX,
-  DEBUG_AI_DELAY_MS, DEFAULT_AI_MODELS, PROVIDER_LABELS,
-  DEBUG_COMMANDS, DEBUG_COMMAND_VALUES,
-  ANTHROPIC_API_VERSION, ANTHROPIC_API_URL,
-} from './constants.js'
+// vanilla core
+export { initHalohalo } from './init.js'
+export { AiApiError, httpStatusToErrorType, PROVIDER_CONFIGS } from './providers.js'
+export { callProvider, callAnthropicWithTools } from './fetch.js'
+export { searchItems, makeSearchTool } from './search.js'
+export { createProviderConfig } from './createProviderConfig.js'
+export { createCompletion } from './createCompletion.js'
+export { getAiRefinement, parseAiResponse } from './aiService.js'
+export { getAgenticRefinement } from './agenticAiService.js'
+export { PROVIDERS, PROVIDER_MODELS, initModels, initApiKeys } from './models.js'
+export { getAiProvider, isAgenticModeEnabled, getAiModel, getProviderLabel } from './prefs.js'
+export { checkConnectivity } from './connectivity.js'
+export {
+  LS_AI_PROVIDER, LS_AGENTIC_MODE, LS_APIKEY_PREFIX, LS_AI_MODEL_PREFIX,
+  AI_MAX_TOKENS, AI_AGENTIC_MAX_TOKENS, AGENTIC_MAX_TOOL_TURNS,
+  AI_DESC_REGEX, AI_FIX_REGEX,
+  DEBUG_AI_DELAY_MS, DEFAULT_AI_MODELS, PROVIDER_LABELS,
+  DEBUG_COMMANDS, DEBUG_COMMAND_VALUES,
+  ANTHROPIC_API_VERSION, ANTHROPIC_API_URL,
+} from './constants.js'

package/init.js

@@ -1,33 +1,33 @@
-// ─── halohalo module singleton ────────────────────────────────────────────────
-// Holds app-injected config. Call initHalohalo() before using aiService or
-// agenticAiService.
-
-let _buildPrompt = null
-let _systemPrompt = null
-
-/**
- * Register app-specific AI config. Call once at app init.
- *
- * @param {{
- *   buildPrompt: (params: object) => string,
- *   systemPrompt?: string,
- * }} config
- *
- * buildPrompt receives { finding, descText, fixText, note } and must return
- * the user-turn prompt string for single-turn refinement.
- *
- * systemPrompt is used for agentic (tool-use) mode. If omitted, agentic mode
- * falls back to a generic instruction.
- */
-export function initHalohalo({ buildPrompt, systemPrompt = null }) {
-  _buildPrompt = buildPrompt
-  _systemPrompt = systemPrompt
-}
-
-export function getBuildPrompt() {
-  return _buildPrompt
-}
-
-export function getSystemPrompt() {
-  return _systemPrompt
-}
+// ─── halohalo module singleton ────────────────────────────────────────────────
+// Holds app-injected config. Call initHalohalo() before using aiService or
+// agenticAiService.
+
+let _buildPrompt = null
+let _systemPrompt = null
+
+/**
+ * Register app-specific AI config. Call once at app init.
+ *
+ * @param {{
+ *   buildPrompt: (params: object) => string,
+ *   systemPrompt?: string,
+ * }} config
+ *
+ * buildPrompt receives { finding, descText, fixText, note } and must return
+ * the user-turn prompt string for single-turn refinement.
+ *
+ * systemPrompt is used for agentic (tool-use) mode. If omitted, agentic mode
+ * falls back to a generic instruction.
+ */
+export function initHalohalo({ buildPrompt, systemPrompt = null }) {
+  _buildPrompt = buildPrompt
+  _systemPrompt = systemPrompt
+}
+
+export function getBuildPrompt() {
+  return _buildPrompt
+}
+
+export function getSystemPrompt() {
+  return _systemPrompt
+}

package/models.js

@@ -1,38 +1,48 @@
-import { getAdapter } from '@ulam/sawsawan'
-import { LS_AI_MODEL_PREFIX, LS_APIKEY_PREFIX, DEFAULT_AI_MODELS } from './constants.js'
-
-export const PROVIDERS = [
-  { id: 'anthropic', label: 'Anthropic (Claude)', placeholderKey: 'settings.api_placeholder_anthropic' },
-  { id: 'openai',    label: 'OpenAI (GPT)',        placeholderKey: 'settings.api_placeholder_openai'    },
-  { id: 'google',    label: 'Google (Gemini)',      placeholderKey: 'settings.api_placeholder_google'    },
-  { id: 'microsoft', label: 'Microsoft (Copilot)', placeholderKey: 'settings.api_placeholder_default'   },
-]
-
-export const PROVIDER_MODELS = {
-  anthropic: [
-    { id: 'claude-haiku-4-5-20251001', label: 'Claude Haiku 4.5, fast, low cost' },
-    { id: 'claude-sonnet-4-6',         label: 'Claude Sonnet 4.6, balanced (default)' },
-    { id: 'claude-opus-4-7',           label: 'Claude Opus 4.7, most capable' },
-  ],
-  openai: [
-    { id: 'gpt-4o-mini', label: 'GPT-4o Mini, fast, low cost' },
-    { id: 'gpt-4o',      label: 'GPT-4o, balanced (default)' },
-  ],
-  google: [
-    { id: 'gemini-1.5-flash', label: 'Gemini 1.5 Flash, fast (default)' },
-    { id: 'gemini-1.5-pro',   label: 'Gemini 1.5 Pro, most capable' },
-  ],
-  microsoft: [],
-}
-
-export function initModels() {
-  return Object.fromEntries(
-    PROVIDERS.map(p => [p.id, getAdapter().readPref(`${LS_AI_MODEL_PREFIX}${p.id}`) || DEFAULT_AI_MODELS[p.id] || ''])
-  )
-}
-
-export function initApiKeys() {
-  return Object.fromEntries(
-    PROVIDERS.map(p => [p.id, window.electronAPI ? '' : getAdapter().readPref(`${LS_APIKEY_PREFIX}${p.id}`) || ''])
-  )
-}
+import { LS_AI_MODEL_PREFIX, LS_APIKEY_PREFIX, DEFAULT_AI_MODELS } from './constants.js'
+
+let _adapter = null
+async function getAdapterInstance() {
+  if (!_adapter) {
+    const mod = await import('@ulam/sawsawan')
+    _adapter = mod.getAdapter()
+  }
+  return _adapter
+}
+
+export const PROVIDERS = [
+  { id: 'anthropic', label: 'Anthropic (Claude)', placeholderKey: 'settings.api_placeholder_anthropic' },
+  { id: 'openai',    label: 'OpenAI (GPT)',        placeholderKey: 'settings.api_placeholder_openai'    },
+  { id: 'google',    label: 'Google (Gemini)',      placeholderKey: 'settings.api_placeholder_google'    },
+  { id: 'microsoft', label: 'Microsoft (Copilot)', placeholderKey: 'settings.api_placeholder_default'   },
+]
+
+export const PROVIDER_MODELS = {
+  anthropic: [
+    { id: 'claude-haiku-4-5-20251001', label: 'Claude Haiku 4.5, fast, low cost' },
+    { id: 'claude-sonnet-4-6',         label: 'Claude Sonnet 4.6, balanced (default)' },
+    { id: 'claude-opus-4-7',           label: 'Claude Opus 4.7, most capable' },
+  ],
+  openai: [
+    { id: 'gpt-4o-mini', label: 'GPT-4o Mini, fast, low cost' },
+    { id: 'gpt-4o',      label: 'GPT-4o, balanced (default)' },
+  ],
+  google: [
+    { id: 'gemini-1.5-flash', label: 'Gemini 1.5 Flash, fast (default)' },
+    { id: 'gemini-1.5-pro',   label: 'Gemini 1.5 Pro, most capable' },
+  ],
+  microsoft: [],
+}
+
+export function initModels() {
+  const adapter = getAdapterInstance()
+  return Object.fromEntries(
+    PROVIDERS.map(p => [p.id, adapter.readPref(`${LS_AI_MODEL_PREFIX}${p.id}`) || DEFAULT_AI_MODELS[p.id] || ''])
+  )
+}
+
+export function initApiKeys() {
+  const adapter = getAdapterInstance()
+  return Object.fromEntries(
+    PROVIDERS.map(p => [p.id, window.electronAPI ? '' : adapter.readPref(`${LS_APIKEY_PREFIX}${p.id}`) || ''])
+  )
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulam/halohalo",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "AI service adapters, model configuration, and provider abstraction.",
   "type": "module",
   "license": "MIT",

package/providers.js

@@ -60,9 +60,11 @@ export const PROVIDER_CONFIGS = {
   },
 
   google: {
-    buildUrl: (key, model) =>
-      `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${key}`,
-    buildHeaders: () => ({ 'Content-Type': 'application/json' }),
+    url: 'https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent',
+    buildHeaders: (key) => ({
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${key}`,
+    }),
     buildBody: (prompt, _model, maxTokens) => JSON.stringify({
       contents: [{ parts: [{ text: prompt }] }],
       generationConfig: { maxOutputTokens: maxTokens },

package/react.js

@@ -1,2 +1,2 @@
-export { useProviderConfig } from './useProviderConfig.js'
-export { useCompletion } from './useCompletion.js'
+export { useProviderConfig } from './useProviderConfig.js'
+export { useCompletion } from './useCompletion.js'

package/useCompletion.js

@@ -1,17 +1,17 @@
-import { useState, useEffect } from 'react'
-import { createCompletion } from './createCompletion.js'
-
-export function useCompletion(options = {}) {
-  const [instance] = useState(createCompletion)
-  const [state, setState] = useState({ loading: false, animating: false })
-
-  useEffect(() => instance.subscribe(setState), [instance])
-  useEffect(() => () => instance.cancel(), [instance])
-
-  return {
-    loading: state.loading,
-    animating: state.animating,
-    complete: (callOptions) => instance.complete({ ...options, ...callOptions }),
-    cancel: () => instance.cancel(),
-  }
-}
+import { useState, useEffect } from 'react'
+import { createCompletion } from './createCompletion.js'
+
+export function useCompletion(options = {}) {
+  const [instance] = useState(createCompletion)
+  const [state, setState] = useState({ loading: false, animating: false })
+
+  useEffect(() => instance.subscribe(setState), [instance])
+  useEffect(() => () => instance.cancel(), [instance])
+
+  return {
+    loading: state.loading,
+    animating: state.animating,
+    complete: (callOptions) => instance.complete({ ...options, ...callOptions }),
+    cancel: () => instance.cancel(),
+  }
+}

package/useProviderConfig.js

@@ -1,22 +1,27 @@
-import { useState, useCallback, useEffect } from 'react'
-import { createProviderConfig } from './createProviderConfig.js'
-
-export function useProviderConfig(storageKeys, providers) {
-  const [config] = useState(() => createProviderConfig(storageKeys, providers))
-  const [, rerender] = useState(0)
-  useEffect(() => config.subscribe(() => rerender(n => n + 1)), [config])
-
-  return {
-    provider: config.provider,
-    models: config.models,
-    mode: config.mode,
-    providers: config.providers,
-    setProvider: useCallback((id) => config.setProvider(id), [config]),
-    setModel: useCallback((pid, mid) => config.setModel(pid, mid), [config]),
-    setMode: useCallback((v) => config.setMode(v), [config]),
-    setKey: useCallback((pid, v) => config.setKey(pid, v), [config]),
-    getKey: useCallback((pid) => config.getKey(pid), [config]),
-    getModel: useCallback((pid) => config.getModel(pid), [config]),
-    getLabel: useCallback((pid) => config.getLabel(pid), [config]),
-  }
-}
+import { useState, useCallback, useSyncExternalStore } from 'react'
+import { createProviderConfig } from './createProviderConfig.js'
+
+export function useProviderConfig(storageKeys, providers) {
+  const [config] = useState(() => createProviderConfig(storageKeys, providers))
+
+  const snapshot = useSyncExternalStore(
+    (listen) => config.subscribe(listen),
+    () => ({
+      provider: config.provider,
+      models: config.models,
+      mode: config.mode,
+      providers: config.providers,
+    })
+  )
+
+  return {
+    ...snapshot,
+    setProvider: useCallback((id) => config.setProvider(id), [config]),
+    setModel: useCallback((pid, mid) => config.setModel(pid, mid), [config]),
+    setMode: useCallback((v) => config.setMode(v), [config]),
+    setKey: useCallback((pid, v) => config.setKey(pid, v), [config]),
+    getKey: useCallback((pid) => config.getKey(pid), [config]),
+    getModel: useCallback((pid) => config.getModel(pid), [config]),
+    getLabel: useCallback((pid) => config.getLabel(pid), [config]),
+  }
+}