@7n/tauri-components 0.0.1

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@7n/tauri-components",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Shared LLM agent engine + Vue/Quasar UI for Tauri apps (chat, journal, trust-tier approval).",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./vue": "./src/vue/index.js",
+    "./components": "./src/components/index.js"
+  },
+  "files": [
+    "src",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "!**/__tests__/**",
+    "!**/fixtures/**"
+  ],
+  "dependencies": {
+    "marked": "^18.0.5"
+  },
+  "peerDependencies": {
+    "@tauri-apps/api": "^2.0.0",
+    "@tauri-apps/plugin-http": "^2.0.0",
+    "quasar": "^2.0.0",
+    "vue": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tauri-apps/api": { "optional": true },
+    "@tauri-apps/plugin-http": { "optional": true },
+    "quasar": { "optional": true }
+  },
+  "knip": {
+    "ignoreDependencies": [
+      "marked"
+    ]
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
+  }
+}

package/src/components/AgentDialog.vue

@@ -0,0 +1,170 @@
+<template>
+  <BaseDialog
+    @update:model-value="val => emit('update:modelValue', val)"
+    @show="onShow"
+    :model-value="modelValue"
+    title="Agent (local LLM)"
+    icon="sym_o_smart_toy"
+    :width="560"
+    body-class="q-gutter-sm"
+  >
+    <template #header>
+      <q-btn @click="showConfig = !showConfig" icon="sym_o_tune" flat round dense size="sm" title="omlx config" />
+    </template>
+
+    <template v-if="showConfig">
+      <q-input v-model="baseUrl" dense outlined label="omlx base URL" />
+      <q-input v-model="model" dense outlined label="model" />
+      <q-input v-model="apiKey" dense outlined label="API key" type="password" />
+      <q-separator class="q-my-sm" />
+    </template>
+
+    <div v-if="turns.length" ref="logEl" class="chat-log">
+      <template v-for="(turn, i) in turns" :key="i">
+        <div v-if="turn.role === 'user'" class="chat-user">{{ turn.text }}</div>
+        <RequestView v-else :result="turn.result" />
+      </template>
+      <div v-if="running" class="chat-thinking">
+        <q-spinner-dots size="18px" /> думаю…
+      </div>
+    </div>
+
+    <q-input
+      v-model="prompt"
+      @keyup.ctrl.enter="send"
+      dense
+      outlined
+      autofocus
+      type="textarea"
+      autogrow
+      :label="inputLabel"
+      hint="наприклад: Create a task named deploy in /Users/.../mt, agent mode"
+    />
+
+    <!-- jscpd:ignore-start — formal footer markup; jscpd html-mode aligns its
+         attribute tokens with an unrelated import block (no shared logic) -->
+    <template #actions>
+      <DialogActions
+        @submit="send"
+        cancel-label="Закрити"
+        :submit-label="sendLabel"
+        icon="sym_o_play_arrow"
+        :disable="sendDisabled"
+        :loading="running"
+      />
+    </template>
+    <!-- jscpd:ignore-end -->
+  </BaseDialog>
+</template>
+
+<script setup>
+import { computed, nextTick, ref } from 'vue'
+import { useQuasar } from 'quasar'
+import BaseDialog from './BaseDialog.vue'
+import DialogActions from './DialogActions.vue'
+import RequestView from './RequestView.vue'
+
+// The agent gateway is injected by the host app (`useAgent({ catalog, … })` from
+// @7n/tauri-components/vue), so this dialog stays domain-free and testable.
+const props = defineProps({
+  modelValue: { type: Boolean, default: false },
+  agent: { type: Object, required: true },
+})
+const emit = defineEmits(['update:modelValue', 'ran'])
+
+const $q = useQuasar()
+const { baseUrl, model, apiKey, saveOmlx, loadOmlxEnv, request, respond } = props.agent
+
+const prompt = ref('')
+const running = ref(false)
+const turns = ref([])
+const requestId = ref(null)
+const logEl = ref(null)
+const showConfig = ref(false)
+
+// Labels shift once a conversation is under way (fresh request → follow-up).
+const inputLabel = computed(() => (turns.value.length ? 'Повідомлення' : 'Prompt'))
+const sendLabel = computed(() => (turns.value.length ? 'Надіслати' : 'Запустити'))
+const sendDisabled = computed(() => running.value || !prompt.value.trim())
+
+/**
+ * Pull omlx config from the user's global settings; reset the conversation.
+ */
+async function onShow() {
+  prompt.value = ''
+  turns.value = []
+  requestId.value = null
+  await loadOmlxEnv()
+}
+
+/**
+ * Scroll the transcript to the latest turn after the DOM settles.
+ */
+async function scrollToEnd() {
+  await nextTick()
+  if (logEl.value) logEl.value.scrollTop = logEl.value.scrollHeight
+}
+
+/**
+ * Append an agent turn, latch the conversation id, refresh the graph on writes.
+ * @param {object} outcome structured result from request/respond
+ */
+function apply(outcome) {
+  if (outcome.requestId) requestId.value = outcome.requestId
+  turns.value.push({ role: 'agent', result: outcome })
+  if (outcome.actions?.some(action => action.envelope?.ok)) emit('ran')
+  scrollToEnd()
+}
+
+/**
+ * Send the current message: start a new request, or resume the conversation.
+ */
+async function send() {
+  const text = prompt.value.trim()
+  if (!text || running.value) return
+  prompt.value = ''
+  turns.value.push({ role: 'user', text })
+  scrollToEnd()
+  running.value = true
+  try {
+    saveOmlx()
+    apply(await (requestId.value ? respond(requestId.value, text) : request(text)))
+  } catch (error) {
+    $q.notify({ type: 'negative', message: String(error?.message ?? error) })
+  }
+  finally {
+    running.value = false
+  }
+}
+</script>
+
+<style scoped>
+.chat-log {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  max-height: 46vh;
+  overflow-y: auto;
+  padding: 2px;
+}
+
+.chat-user {
+  align-self: flex-end;
+  max-width: 85%;
+  padding: 7px 11px;
+  border-radius: 12px 12px 2px 12px;
+  background: color-mix(in srgb, #0a84ff 18%, transparent);
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  font-size: 13px;
+  line-height: 1.45;
+}
+
+.chat-thinking {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+  opacity: 0.7;
+}
+</style>

package/src/components/AuditDialog.vue

@@ -0,0 +1,259 @@
+<template>
+  <BaseDialog
+    @update:model-value="val => emit('update:modelValue', val)"
+    @show="refresh"
+    :model-value="modelValue"
+    title="Request journal"
+    icon="sym_o_history"
+    :width="680"
+    body-class=""
+  >
+    <template #header>
+      <q-btn @click="refresh" icon="sym_o_refresh" flat round dense size="sm" :loading="loading" title="Refresh" />
+    </template>
+
+    <div v-if="!records.length && !loading" class="audit-empty">No requests yet</div>
+
+    <div v-for="rec in records" :key="rec.id" class="audit-row">
+      <div @click="toggle(rec.id)" class="audit-head">
+        <span class="state-pill" :style="{ '--c': statusColor(rec.status) }">
+          <span class="state-pill__dot" />
+          {{ rec.status }}
+        </span>
+        <span class="audit-actor">{{ rec.actor?.kind }}{{ rec.actor?.id ? `:${rec.actor.id}` : '' }}</span>
+        <span class="audit-intent">{{ rec.intent }}</span>
+        <q-space />
+        <span class="audit-time">{{ fmtTime(rec.createdAt) }}</span>
+      </div>
+
+      <div v-if="expandedId === rec.id" class="audit-body">
+        <RequestView @respond="msg => onRespond(rec, msg)" :result="rec" :busy="busyId === rec.id" />
+        <div v-if="rec.status === 'needs_approval' && rec.pendingApproval" class="audit-approval">
+          <div class="audit-pending">
+            Approve action: <code>{{ rec.pendingApproval.tool }}({{ JSON.stringify(rec.pendingApproval.input) }})</code>
+          </div>
+          <div class="row q-gutter-sm">
+            <q-btn
+              @click="onApprove(rec, true)"
+              label="Підтвердити"
+              color="negative"
+              unelevated
+              no-caps
+              :loading="busyId === rec.id"
+            />
+            <q-btn @click="onApprove(rec, false)" label="Відхилити" flat no-caps :disable="busyId === rec.id" />
+          </div>
+        </div>
+      </div>
+    </div>
+  </BaseDialog>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { useQuasar } from 'quasar'
+import BaseDialog from './BaseDialog.vue'
+import RequestView from './RequestView.vue'
+
+const STATUS_COLOR = {
+  pending: '#8e8e93',
+  running: '#0a84ff',
+  done: '#30d158',
+  partial: '#ff9f0a',
+  needs_clarification: '#64d2ff',
+  needs_approval: '#ff9f0a',
+  failed: '#ff453a',
+  rejected: '#8e8e93',
+}
+
+// The agent gateway (journal + respond + approve) is injected by the host app,
+// keeping this dialog domain-free.
+const props = defineProps({
+  modelValue: { type: Boolean, default: false },
+  agent: { type: Object, required: true },
+})
+const emit = defineEmits(['update:modelValue', 'changed'])
+
+const $q = useQuasar()
+const { journal, respond, approve } = props.agent
+
+const records = ref([])
+const loading = ref(false)
+const expandedId = ref(null)
+const busyId = ref(null)
+
+/**
+ * @param {string} status request status
+ * @returns {string} accent color
+ */
+function statusColor(status) {
+  return STATUS_COLOR[status] ?? '#8e8e93'
+}
+
+/**
+ * @param {number} millis epoch millis
+ * @returns {string} locale time
+ */
+function fmtTime(millis) {
+  return millis ? new Date(millis).toLocaleString() : ''
+}
+
+/**
+ * Reload the journal list.
+ */
+async function refresh() {
+  loading.value = true
+  try {
+    records.value = await journal.list()
+  }
+  catch (error) {
+    $q.notify({ type: 'negative', message: String(error?.message ?? error) })
+  }
+  finally {
+    loading.value = false
+  }
+}
+
+/**
+ * @param {string} id record id to expand/collapse
+ */
+function toggle(id) {
+  expandedId.value = expandedId.value === id ? null : id
+}
+
+/**
+ * Answer a pending clarification on a journaled request, then refresh.
+ * @param {object} rec the record
+ * @param {string} message the human's answer
+ */
+async function onRespond(rec, message) {
+  busyId.value = rec.id
+  try {
+    await respond(rec.id, message)
+    await refresh()
+    emit('changed')
+  }
+  catch (error) {
+    $q.notify({ type: 'negative', message: String(error?.message ?? error) })
+  }
+  finally {
+    busyId.value = null
+  }
+}
+
+/**
+ * Approve or reject a pending destructive action, then refresh.
+ * @param {object} rec the record
+ * @param {boolean} ok true to approve (execute), false to reject
+ */
+async function onApprove(rec, ok) {
+  busyId.value = rec.id
+  try {
+    await approve(rec.id, ok)
+    await refresh()
+    emit('changed')
+  }
+  catch (error) {
+    $q.notify({ type: 'negative', message: String(error?.message ?? error) })
+  }
+  finally {
+    busyId.value = null
+  }
+}
+</script>
+
+<style scoped>
+.audit-empty {
+  text-align: center;
+  padding: 40px 0;
+  font-size: 13px;
+  opacity: 0.4;
+}
+
+.audit-approval {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  margin-top: 8px;
+  padding: 10px;
+  border-radius: 8px;
+  background: color-mix(in srgb, #ff9f0a 12%, transparent);
+}
+
+.audit-pending {
+  font-size: 13px;
+  overflow-wrap: anywhere;
+}
+
+.audit-row {
+  border-bottom: 1px solid rgb(255 255 255 / 7%);
+}
+
+.body--light .audit-row {
+  border-bottom-color: rgb(0 0 0 / 7%);
+}
+
+.audit-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 4px;
+  cursor: pointer;
+}
+
+.audit-head:hover {
+  background: rgb(255 255 255 / 5%);
+}
+
+.body--light .audit-head:hover {
+  background: rgb(0 0 0 / 4%);
+}
+
+.audit-actor {
+  font-family: 'SF Mono', ui-monospace, 'JetBrains Mono', monospace;
+  font-size: 11px;
+  opacity: 0.6;
+  flex: 0 0 auto;
+}
+
+.audit-intent {
+  font-size: 13px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.audit-time {
+  font-size: 11px;
+  opacity: 0.4;
+  flex: 0 0 auto;
+}
+
+.audit-body {
+  padding: 6px 4px 12px;
+}
+
+.state-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  height: 20px;
+  padding: 0 8px;
+  border-radius: 6px;
+  font-family: 'SF Mono', ui-monospace, 'JetBrains Mono', monospace;
+  font-size: 11px;
+  color: var(--c);
+  background: color-mix(in srgb, var(--c) 14%, transparent);
+  border: 1px solid color-mix(in srgb, var(--c) 28%, transparent);
+  flex: 0 0 auto;
+}
+
+.state-pill__dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--c);
+}
+</style>

package/src/components/BaseDialog.vue

@@ -0,0 +1,58 @@
+<template>
+  <q-dialog
+    @update:model-value="value => emit('update:modelValue', value)"
+    v-bind="$attrs"
+    :model-value="modelValue"
+  >
+    <q-card class="base-dialog" :style="{ width: `${width}px` }">
+      <q-card-section class="row items-center no-wrap q-pb-sm">
+        <q-icon v-if="icon" :name="icon" size="20px" class="q-mr-sm" />
+        <span class="base-dialog__title">{{ title }}</span>
+        <q-space />
+        <slot name="header" />
+        <q-btn v-close-popup icon="sym_o_close" flat round dense size="sm" />
+      </q-card-section>
+
+      <q-separator />
+
+      <q-card-section :class="bodyClass">
+        <slot />
+      </q-card-section>
+
+      <q-separator />
+
+      <q-card-actions align="right" class="q-pa-md">
+        <slot name="actions" />
+      </q-card-actions>
+    </q-card>
+  </q-dialog>
+</template>
+
+<script setup>
+// Shared shell for app dialogs (header icon+title+close, body slot, actions
+// slot). Keeps the Quasar dialog boilerplate in one place so feature dialogs
+// (create task, agent, …) carry only their own content. `$attrs` forwards
+// listeners like @show to the underlying q-dialog.
+defineOptions({ inheritAttrs: false })
+
+defineProps({
+  modelValue: { type: Boolean, default: false },
+  title: { type: String, required: true },
+  icon: { type: String, default: '' },
+  width: { type: Number, default: 520 },
+  bodyClass: { type: String, default: 'q-gutter-md' },
+})
+const emit = defineEmits(['update:modelValue'])
+</script>
+
+<style scoped>
+.base-dialog {
+  max-width: 92vw;
+}
+
+.base-dialog__title {
+  font-family: 'SF Mono', ui-monospace, 'JetBrains Mono', monospace;
+  font-size: 15px;
+  font-weight: 600;
+}
+</style>

package/src/components/DialogActions.vue

@@ -0,0 +1,26 @@
+<template>
+  <q-btn v-close-popup :label="cancelLabel" flat no-caps />
+  <q-btn
+    @click="emit('submit')"
+    :label="submitLabel"
+    :icon="icon"
+    :disable="disable"
+    :loading="loading"
+    color="primary"
+    unelevated
+    no-caps
+  />
+</template>
+
+<script setup>
+// Shared dialog footer: a close button plus a primary action. Keeps the
+// cancel + submit pattern canonical across feature dialogs (see BaseDialog).
+defineProps({
+  cancelLabel: { type: String, default: 'Скасувати' },
+  submitLabel: { type: String, required: true },
+  icon: { type: String, default: undefined },
+  disable: { type: Boolean, default: false },
+  loading: { type: Boolean, default: false },
+})
+const emit = defineEmits(['submit'])
+</script>

package/src/components/RequestView.vue

@@ -0,0 +1,101 @@
+<template>
+  <div class="req-view">
+    <span class="state-pill" :style="{ '--c': statusColor }">
+      <span class="state-pill__dot" />
+      {{ result.status }}
+    </span>
+
+    <div v-if="result.summary" class="req-summary">{{ result.summary }}</div>
+    <div v-if="result.question" class="req-summary">{{ result.question }}</div>
+    <div v-if="result.error" class="req-error">{{ result.error }}</div>
+
+    <div v-if="result.actions?.length" class="req-actions">
+      <div v-for="(action, i) in result.actions" :key="i" class="req-action">
+        <q-icon
+          :name="action.envelope?.ok ? 'sym_o_check_circle' : 'sym_o_error'"
+          :color="action.envelope?.ok ? 'positive' : 'negative'"
+          size="14px"
+        />
+        <code>{{ action.tool }}({{ JSON.stringify(action.input) }})</code>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+
+const STATUS_COLOR = {
+  pending: '#8e8e93',
+  running: '#0a84ff',
+  done: '#30d158',
+  partial: '#ff9f0a',
+  needs_clarification: '#64d2ff',
+  needs_approval: '#ff9f0a',
+  failed: '#ff453a',
+  rejected: '#8e8e93',
+}
+
+const props = defineProps({
+  result: { type: Object, required: true },
+})
+
+const statusColor = computed(() => STATUS_COLOR[props.result.status] ?? '#8e8e93')
+</script>
+
+<style scoped>
+.req-view {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.req-summary {
+  line-height: 1.5;
+  white-space: pre-wrap;
+  font-size: 13px;
+}
+
+.req-error {
+  color: #ff6b60;
+  font-size: 13px;
+}
+
+.req-actions {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+}
+
+.req-action {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-family: 'SF Mono', ui-monospace, 'JetBrains Mono', monospace;
+  font-size: 11px;
+  opacity: 0.8;
+  overflow-wrap: anywhere;
+}
+
+.state-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  align-self: flex-start;
+  height: 20px;
+  padding: 0 8px;
+  border-radius: 6px;
+  font-family: 'SF Mono', ui-monospace, 'JetBrains Mono', monospace;
+  font-size: 11px;
+  color: var(--c);
+  background: color-mix(in srgb, var(--c) 14%, transparent);
+  border: 1px solid color-mix(in srgb, var(--c) 28%, transparent);
+}
+
+.state-pill__dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--c);
+}
+</style>

package/src/components/index.js

@@ -0,0 +1,10 @@
+// `@7n/tauri-components/components` — Quasar dialogs for the agent. AgentDialog
+// and AuditDialog take the injected `agent` gateway (from ./vue useAgent) via a
+// prop; the rest are pure props-only building blocks. Requires the host app to
+// provide vue + quasar (peer deps) and to have Quasar installed.
+
+export { default as AgentDialog } from './AgentDialog.vue'
+export { default as AuditDialog } from './AuditDialog.vue'
+export { default as BaseDialog } from './BaseDialog.vue'
+export { default as DialogActions } from './DialogActions.vue'
+export { default as RequestView } from './RequestView.vue'

package/src/core/agent-handler.js

@@ -0,0 +1,171 @@
+import { runAgent } from './llm.js'
+
+// Agent-gateway handlers — start / resume / approve the agent loop on behalf of a
+// caller (human via UI or agent via MCP). They own the journal lifecycle and
+// return a structured result contract.
+//
+// All collaborators are injected (no module-level singletons): `dispatch`,
+// `journal`, the scoped `tools` manifest, the `gate` decision fn, `buildSystem`
+// (turns optional grounding context into a system prompt) and `grounding` (an
+// optional read tool whose output grounds the prompt). createAgentKit wires
+// these from an app catalog; tests pass fakes.
+//
+// Trust: destructive tool calls from an agent pause as `needs_approval` (the
+// loop never executes them); a human approves later via handleApprove.
+
+const QUESTION_RE = /\?\s*$/
+
+/**
+ * @param {string} text candidate text
+ * @returns {boolean} true when text ends with a question mark
+ */
+function isQuestion(text) {
+  return typeof text === 'string' && QUESTION_RE.test(text.trim())
+}
+
+/**
+ * Derive the structured result fields from a runAgent result.
+ * @param {object} result runAgent result
+ * @returns {{ status: string, summary: string|null, question: string|null, pendingApproval: object|null }} fields
+ */
+function finalize(result) {
+  const question = isQuestion(result.content) ? result.content : null
+  let status = 'done'
+  if (result.stopped === 'needs_approval') status = 'needs_approval'
+  else if (result.stopped === 'max_steps') status = 'partial'
+  else if (question) status = 'needs_clarification'
+  return {
+    status,
+    summary: question ? null : (result.content || null),
+    question,
+    pendingApproval: result.pendingApproval ?? null,
+  }
+}
+
+/**
+ * Run the loop (fresh or resumed), persist to the journal, return the envelope.
+ * @param {{ requestId: string, runArgs: object, baseActions: object[], journal: object }} ctx run context
+ * @returns {Promise<object>} structured result envelope
+ */
+async function runAndJournal({ requestId, runArgs, baseActions, journal }) {
+  let result
+  try {
+    result = await runAgent(runArgs)
+  }
+  catch (error) {
+    await journal.update(requestId, { status: 'failed', error: String(error?.message ?? error) })
+    return { requestId, status: 'failed', summary: null, actions: baseActions, question: null, pendingApproval: null }
+  }
+
+  const fields = finalize(result)
+  const actions = [...baseActions, ...result.trace]
+  await journal.update(requestId, { ...fields, messages: result.messages, actions })
+  return { requestId, ...fields, actions }
+}
+
+/**
+ * Fetch optional grounding context via a read tool; {} when not configured / on failure.
+ * @param {Function} dispatch tool dispatcher
+ * @param {{ tool: string, key?: string, fallback?: unknown }} [grounding] grounding config
+ * @returns {Promise<object>} context object keyed by grounding.key (default "grounding")
+ */
+async function groundingContext(dispatch, grounding) {
+  if (!grounding?.tool) return {}
+  const key = grounding.key ?? 'grounding'
+  const fallback = grounding.fallback ?? []
+  try {
+    const res = await dispatch(grounding.tool, {})
+    return { [key]: res?.ok ? res.output : fallback }
+  }
+  catch {
+    return { [key]: fallback }
+  }
+}
+
+/**
+ * Start a new agent request.
+ * @param {{ intent: string, actor: object, chat: Function, dispatch: Function, journal: object, tools: object[], gate: Function, buildSystem?: Function, grounding?: object }} opts request parameters
+ * @returns {Promise<object>} structured result envelope
+ */
+export async function handleRequest({ intent, actor, chat, dispatch, journal, tools, gate, buildSystem, grounding }) {
+  const id = await journal.create({ intent, actor })
+  await journal.update(id, { status: 'running' })
+  const ctx = await groundingContext(dispatch, grounding)
+  const system = buildSystem ? buildSystem(ctx) : undefined
+  return runAndJournal({
+    requestId: id,
+    baseActions: [],
+    journal,
+    runArgs: { system, prompt: intent, chat, dispatch, tools, gate },
+  })
+}
+
+/**
+ * Resume a conversation with a follow-up / clarification answer.
+ * @param {{ requestId: string, message: string, actor: object, chat: Function, dispatch: Function, journal: object, tools: object[], gate: Function }} opts resume parameters
+ * @returns {Promise<object>} updated result envelope
+ */
+export async function handleRespond({ requestId, message, chat, dispatch, journal, tools, gate }) {
+  let record
+  try {
+    record = await journal.load(requestId)
+  }
+  catch {
+    return { requestId, status: 'failed', summary: null, actions: [], question: 'Request not found.', pendingApproval: null }
+  }
+
+  if (record.status === 'running' || !Array.isArray(record.messages) || record.messages.length === 0) {
+    return { requestId, status: record.status, summary: record.summary, actions: record.actions, question: null, pendingApproval: record.pendingApproval ?? null }
+  }
+
+  await journal.update(requestId, { status: 'running' })
+  return runAndJournal({
+    requestId,
+    baseActions: record.actions ?? [],
+    journal,
+    runArgs: { messages: [...record.messages, { role: 'user', content: message }], chat, dispatch, tools, gate },
+  })
+}
+
+/**
+ * Approve (or reject) a pending destructive action. Executes with the approver's
+ * (human) authority via the injected dispatch — no gate.
+ * @param {{ requestId: string, approve: boolean, dispatch: Function, journal: object }} opts approval parameters
+ * @returns {Promise<object>} updated result envelope
+ */
+export async function handleApprove({ requestId, approve, dispatch, journal }) {
+  let record
+  try {
+    record = await journal.load(requestId)
+  }
+  catch {
+    return { requestId, status: 'failed', summary: null, actions: [], question: 'Request not found.', pendingApproval: null }
+  }
+
+  if (record.status !== 'needs_approval' || !record.pendingApproval) {
+    return { requestId, status: record.status, summary: record.summary, actions: record.actions ?? [], question: null, pendingApproval: null }
+  }
+
+  if (!approve) {
+    const fields = { status: 'rejected', summary: 'Rejected by human.', pendingApproval: null }
+    await journal.update(requestId, fields)
+    return { requestId, ...fields, actions: record.actions ?? [], question: null }
+  }
+
+  const { tool, input } = record.pendingApproval
+  await journal.update(requestId, { status: 'running' })
+  const envelope = await dispatch(tool, input)
+  const actions = [...(record.actions ?? []), { tool, input, envelope }]
+
+  if (!envelope.ok) {
+    // Execution failed (e.g. transient) — stay needs_approval so the human can
+    // retry after fixing; keep pendingApproval, record the error and the attempt.
+    const error = envelope.error?.message ?? 'execution failed'
+    await journal.update(requestId, { status: 'needs_approval', actions, error })
+    return { requestId, status: 'needs_approval', summary: null, actions, error, question: null, pendingApproval: record.pendingApproval }
+  }
+
+  const summary = `Approved: ${tool} executed.`
+  await journal.update(requestId, { status: 'done', actions, summary, error: null, pendingApproval: null })
+  return { requestId, status: 'done', summary, actions, question: null, pendingApproval: null }
+}

package/src/core/agent-kit.js

@@ -0,0 +1,43 @@
+import { handleApprove, handleRequest, handleRespond } from './agent-handler.js'
+import { createDispatch } from './dispatch.js'
+import { toolManifest } from './manifest.js'
+import { classify, DEFAULT_ACTOR_TIERS, scopedManifest } from './scope.js'
+
+// createAgentKit binds the generic agent machinery to ONE app's tool catalog.
+// It is the single integration seam: an app supplies its catalog, a domain
+// system prompt, a transport (Tauri invoke / CLI spawn / fetch), a journal store
+// and optional grounding, and gets back request/respond/approve plus the derived
+// manifest + scope helpers — all pre-bound, so callers never re-thread the
+// catalog. The `chat` fn stays per-call (its config can change between requests).
+
+/**
+ * @param {object} config kit configuration
+ * @param {object[]} config.catalog tool definitions (required)
+ * @param {string|((ctx: object) => string)} [config.systemPrompt] domain system prompt (or builder from grounding ctx)
+ * @param {(tool: object, input: object) => unknown} [config.transport] backend runner; omit to build the kit without dispatch (manifest/scope only)
+ * @param {object} [config.journal] journal store { create, load, update, list }
+ * @param {Record<string, number>} [config.actorTiers] max executable tier rank per actor kind
+ * @param {{ tool: string, key?: string, fallback?: unknown }} [config.grounding] optional read tool to ground the prompt
+ * @returns {{ dispatch: Function|null, classify: Function, scopedManifest: Function, toolManifest: Function, request: Function, respond: Function, approve: Function }} bound kit
+ */
+export function createAgentKit({ catalog, systemPrompt = '', transport, journal, actorTiers = DEFAULT_ACTOR_TIERS, grounding } = {}) {
+  if (!Array.isArray(catalog)) throw new Error('createAgentKit: catalog (array) is required')
+
+  const dispatch = transport ? createDispatch(catalog, transport) : null
+  const buildSystem = typeof systemPrompt === 'function' ? systemPrompt : () => systemPrompt
+  const toolsFor = actor => scopedManifest(catalog, actorTiers, actor)
+  const gateFor = actor => name => classify(catalog, actorTiers, actor, name)
+
+  return {
+    dispatch,
+    classify: (actor, name) => classify(catalog, actorTiers, actor, name),
+    scopedManifest: actor => toolsFor(actor),
+    toolManifest: allow => toolManifest(catalog, allow),
+    request: ({ intent, actor, chat }) =>
+      handleRequest({ intent, actor, chat, dispatch, journal, tools: toolsFor(actor), gate: gateFor(actor), buildSystem, grounding }),
+    respond: ({ requestId, message, actor, chat }) =>
+      handleRespond({ requestId, message, actor, chat, dispatch, journal, tools: toolsFor(actor), gate: gateFor(actor) }),
+    approve: ({ requestId, approve }) =>
+      handleApprove({ requestId, approve, dispatch, journal }),
+  }
+}

package/src/core/dispatch.js

@@ -0,0 +1,50 @@
+import { getTool } from './tools.js'
+
+// dispatch(name, input): validate input against the tool schema, run it via the
+// injected transport, return the uniform envelope. The transport is the only
+// thing that differs per consumer (Tauri invoke in-app, a CLI spawn in an
+// orchestrator), so the contract stays identical everywhere.
+
+/**
+ * Validate an input object against a tool's schema and custom validator.
+ * @param {object} tool tool definition
+ * @param {object} [input] candidate input
+ * @returns {string|null} error message, or null when valid
+ */
+export function validateInput(tool, input) {
+  const data = input ?? {}
+  for (const [key, spec] of Object.entries(tool.input)) {
+    const value = data[key]
+    if (value === undefined || value === null) {
+      if (spec.required) return `Missing required field: ${key}`
+      continue
+    }
+    if (spec.type === 'string' && typeof value !== 'string') return `Field "${key}" must be a string`
+    if (spec.type === 'object' && (typeof value !== 'object' || Array.isArray(value))) return `Field "${key}" must be an object`
+  }
+  return tool.validate ? tool.validate(data) : null
+}
+
+/**
+ * Build a dispatch function bound to a catalog and a transport.
+ * @param {object[]} catalog tool definitions
+ * @param {(tool: object, input: object) => unknown} transport runs the tool's backend call
+ * @returns {(name: string, input?: object) => Promise<object>} dispatch returning an envelope
+ */
+export function createDispatch(catalog, transport) {
+  return async function dispatch(name, input) {
+    const tool = getTool(catalog, name)
+    if (!tool) return { ok: false, error: { code: 'not_found', message: `Unknown tool: ${name}` } }
+
+    const invalid = validateInput(tool, input)
+    if (invalid) return { ok: false, error: { code: 'validation', message: invalid } }
+
+    try {
+      const output = await transport(tool, input ?? {})
+      return { ok: true, output }
+    }
+    catch (error) {
+      return { ok: false, error: { code: 'io', message: String(error?.message ?? error) } }
+    }
+  }
+}

package/src/core/llm.js

@@ -0,0 +1,90 @@
+// The tool-calling loop and an OpenAI-compatible chat adapter. Both are
+// stateless and domain-agnostic: the system prompt and tool manifest are passed
+// in by the caller (an app builds them from its catalog — see agent-kit.js).
+
+const DEFAULT_SYSTEM = 'You are a tool-using assistant. Call one tool at a time and wait for its result. If the request is ambiguous, ask a clarifying question with no tool call. When done, reply with a plain-text summary and no tool call.'
+
+/**
+ * Run the tool-calling loop until the model answers without a tool call.
+ * Accepts either a fresh prompt or an existing messages[] for sessional resume.
+ * @param {object} params loop parameters
+ * @param {string} [params.prompt] user request (fresh start)
+ * @param {object[]} [params.messages] existing conversation to resume (takes priority over prompt)
+ * @param {(name: string, input: object) => Promise<object>} params.dispatch tool dispatcher returning an envelope
+ * @param {(req: {messages: object[], tools: object[]}) => Promise<object>} params.chat model call returning an assistant message
+ * @param {number} [params.maxSteps] safety cap on loop iterations
+ * @param {string} [params.system] system prompt (only used when building fresh from prompt)
+ * @param {object[]} [params.tools] LLM tool manifest (pass a scoped manifest to restrict)
+ * @param {(name: string) => 'allow'|'approval'|'deny'} [params.gate] per-call decision (default: allow)
+ * @returns {Promise<{content: string, steps: number, trace: object[], messages: object[], stopped?: string, pendingApproval?: object}>} loop result
+ */
+export async function runAgent({ prompt, messages: initialMessages, dispatch, chat, maxSteps = 6, system = DEFAULT_SYSTEM, tools = [], gate = () => 'allow' }) {
+  const messages = initialMessages
+    ? [...initialMessages]
+    : [
+        { role: 'system', content: system },
+        { role: 'user', content: prompt },
+      ]
+  const trace = []
+
+  for (let step = 0; step < maxSteps; step++) {
+    const reply = await chat({ messages, tools })
+    messages.push(reply)
+
+    const calls = reply.tool_calls ?? []
+    if (calls.length === 0) {
+      return { content: reply.content ?? '', steps: step + 1, trace, messages }
+    }
+
+    for (const call of calls) {
+      let input = {}
+      try {
+        input = call.function.arguments ? JSON.parse(call.function.arguments) : {}
+      }
+      catch {
+        // leave input empty — dispatch's schema validation reports the problem
+      }
+
+      const decision = gate(call.function.name)
+      if (decision === 'approval') {
+        // Destructive request from a non-human: pause for human approval.
+        return { content: reply.content ?? '', steps: step + 1, trace, messages, stopped: 'needs_approval', pendingApproval: { tool: call.function.name, input } }
+      }
+
+      const envelope = decision === 'deny'
+        ? { ok: false, error: { code: 'forbidden', message: `Tool "${call.function.name}" is not allowed.` } }
+        : await dispatch(call.function.name, input)
+      trace.push({ tool: call.function.name, input, envelope })
+      messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(envelope) })
+    }
+  }
+
+  return { content: '', steps: maxSteps, trace, messages, stopped: 'max_steps' }
+}
+
+/**
+ * Build a `chat` function that calls an OpenAI-compatible endpoint (omlx).
+ * @param {object} params config
+ * @param {string} params.baseUrl base URL incl. /v1 (e.g. http://127.0.0.1:10240/v1)
+ * @param {string} params.model served model id
+ * @param {string} [params.apiKey] optional bearer token
+ * @param {typeof fetch} [params.fetchFn] fetch implementation (injectable for tests / tauri-http)
+ * @returns {(req: {messages: object[], tools: object[]}) => Promise<object>} chat function
+ */
+export function createOpenAiChat({ baseUrl, model, apiKey, fetchFn = fetch }) {
+  return async function chat({ messages, tools }) {
+    const response = await fetchFn(`${baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
+      },
+      body: JSON.stringify({ model, messages, tools, tool_choice: 'auto' }),
+    })
+    if (!response.ok) {
+      throw new Error(`omlx ${response.status}: ${await response.text()}`)
+    }
+    const data = await response.json()
+    return data.choices[0].message
+  }
+}

package/src/core/manifest.js

@@ -0,0 +1,44 @@
+// Consumer-facing artifacts derived from a tool catalog. The LLM adapter (omlx —
+// OpenAI-compatible MLX server) consumes the OpenAI function-calling shape. The
+// catalog is passed in (see tools.js) so these stay app-agnostic.
+
+/**
+ * Convert a tool input spec into a JSON Schema object.
+ * @param {Record<string, {type: string, required?: boolean, description?: string}>} input tool input spec
+ * @returns {object} JSON Schema for the parameters object
+ */
+export function toJsonSchema(input) {
+  const properties = {}
+  const required = []
+  for (const [key, spec] of Object.entries(input)) {
+    properties[key] = spec.description ? { type: spec.type, description: spec.description } : { type: spec.type }
+    if (spec.required) required.push(key)
+  }
+  return required.length ? { type: 'object', properties, required } : { type: 'object', properties }
+}
+
+/**
+ * OpenAI function-calling tool definitions, optionally filtered (e.g. by scope).
+ * @param {object[]} catalog tool definitions
+ * @param {(tool: object) => boolean} [allow] predicate; default includes all tools
+ * @returns {object[]} OpenAI `tools` array
+ */
+export function toolManifest(catalog, allow = () => true) {
+  return catalog.filter(tool => allow(tool)).map(tool => ({
+    type: 'function',
+    function: {
+      name: tool.name,
+      description: tool.summary,
+      parameters: toJsonSchema(tool.input),
+    },
+  }))
+}
+
+/**
+ * Compact catalog listing (name + summary).
+ * @param {object[]} catalog tool definitions
+ * @returns {{name: string, summary: string}[]} tool list
+ */
+export function listTools(catalog) {
+  return catalog.map(({ name, summary }) => ({ name, summary }))
+}

package/src/core/scope.js

@@ -0,0 +1,52 @@
+import { toolManifest } from './manifest.js'
+import { getTool } from './tools.js'
+
+// Trust scope. Each tool has a tier; each actor kind has a max tier it may
+// EXECUTE directly. Above that:
+//   - agent + destructive → 'approval' (request goes to the human via the journal);
+//   - otherwise           → 'deny'.
+// Humans (UI, at the keyboard) execute everything directly.
+
+const TIER_RANK = { read: 0, write: 1, destructive: 2 }
+export const DEFAULT_ACTOR_TIERS = { human: 2, agent: 1 }
+
+/**
+ * Classify a tool call for an actor.
+ * @param {object[]} catalog tool definitions
+ * @param {Record<string, number>|undefined} actorTiers max executable tier rank per actor kind
+ * @param {{ kind?: string }} actor caller identity
+ * @param {string} toolName tool name
+ * @returns {'allow'|'approval'|'deny'} decision
+ */
+export function classify(catalog, actorTiers, actor, toolName) {
+  const tiers = actorTiers ?? DEFAULT_ACTOR_TIERS
+  const tool = getTool(catalog, toolName)
+  if (!tool) return 'deny'
+  const rank = TIER_RANK[tool.tier] ?? Number.POSITIVE_INFINITY
+  const max = tiers[actor?.kind] ?? 0
+  if (rank <= max) return 'allow'
+  if (tool.tier === 'destructive' && actor?.kind === 'agent') return 'approval'
+  return 'deny'
+}
+
+/**
+ * LLM tool manifest visible to the actor (everything it may run OR request approval for).
+ * @param {object[]} catalog tool definitions
+ * @param {Record<string, number>|undefined} actorTiers max executable tier rank per actor kind
+ * @param {{ kind?: string }} actor caller identity
+ * @returns {object[]} OpenAI tools array
+ */
+export function scopedManifest(catalog, actorTiers, actor) {
+  return toolManifest(catalog, tool => classify(catalog, actorTiers, actor, tool.name) !== 'deny')
+}
+
+/**
+ * Tool names visible to the actor.
+ * @param {object[]} catalog tool definitions
+ * @param {Record<string, number>|undefined} actorTiers max executable tier rank per actor kind
+ * @param {{ kind?: string }} actor caller identity
+ * @returns {string[]} visible tool names
+ */
+export function scopedToolNames(catalog, actorTiers, actor) {
+  return catalog.filter(tool => classify(catalog, actorTiers, actor, tool.name) !== 'deny').map(tool => tool.name)
+}

package/src/core/tools.js

@@ -0,0 +1,14 @@
+// Catalog helpers. A catalog is the app-provided array of tool definitions
+// (`{ tier, name, summary, input, tauri, validate? }`). The package treats it as
+// data passed in — never a module-level singleton — so each consumer app keeps
+// its own domain tool surface while sharing the agent machinery.
+
+/**
+ * Look up a tool by name in a catalog.
+ * @param {object[]} catalog tool definitions
+ * @param {string} name tool name
+ * @returns {object|null} the tool definition, or null if unknown
+ */
+export function getTool(catalog, name) {
+  return catalog.find(tool => tool.name === name) ?? null
+}

package/src/index.js

@@ -0,0 +1,12 @@
+// `@7n/tauri-components` — core (no Vue). The agent loop, tool surface and the
+// kit that binds them to an app catalog. Import this entry from headless
+// consumers (CLI orchestrators, MCP wrappers); the Vue/Quasar layers live under
+// the ./vue and ./components subpaths.
+
+export { createAgentKit } from './core/agent-kit.js'
+export { handleApprove, handleRequest, handleRespond } from './core/agent-handler.js'
+export { createDispatch, validateInput } from './core/dispatch.js'
+export { createOpenAiChat, runAgent } from './core/llm.js'
+export { listTools, toJsonSchema, toolManifest } from './core/manifest.js'
+export { classify, DEFAULT_ACTOR_TIERS, scopedManifest, scopedToolNames } from './core/scope.js'
+export { getTool } from './core/tools.js'

package/src/vue/index.js

@@ -0,0 +1,9 @@
+// `@7n/tauri-components/vue` — Vue + Tauri composables. Wires the core agent kit
+// to the webview (omlx over tauri-http, tools/journal over Tauri invoke).
+// Requires the host app to provide vue + @tauri-apps/* (peer deps) and the
+// tauri-plugin-agent backend commands.
+
+export { useAgent } from './use-agent.js'
+export { useOmlx } from './use-omlx.js'
+export { createTauriJournalStore } from './journal-store-tauri.js'
+export { tauriTransport } from './transports.js'

package/src/vue/journal-store-tauri.js

@@ -0,0 +1,17 @@
+import { invoke } from '@tauri-apps/api/core'
+
+// Webview journal store: routes journal FS through Rust Tauri commands
+// (journal_*), provided by the shared `tauri-plugin-agent` (see SPEC §6). Same
+// shape any other store implements, so agent-handler stays backend-agnostic.
+
+/**
+ * @returns {{ create: (r:object)=>Promise<string>, load: (id:string)=>Promise<object>, update: (id:string,patch:object)=>Promise<void>, list: ()=>Promise<object[]> }} journal store
+ */
+export function createTauriJournalStore() {
+  return {
+    create: ({ intent, actor }) => invoke('journal_create', { intent, actor }),
+    load: id => invoke('journal_load', { id }),
+    update: (id, patch) => invoke('journal_update', { id, patch }),
+    list: () => invoke('journal_list'),
+  }
+}

package/src/vue/transports.js

@@ -0,0 +1,14 @@
+import { invoke } from '@tauri-apps/api/core'
+
+// UI transport: route a tool call to its Tauri command. Input keys map 1:1 to
+// the command's args (already camelCase, e.g. tasksDir). Each consumer app
+// implements the named `tool.tauri` commands in its Rust backend.
+
+/**
+ * @param {object} tool tool definition (uses `tool.tauri`)
+ * @param {object} input tool input, forwarded as command args
+ * @returns {Promise<unknown>} the command result
+ */
+export function tauriTransport(tool, input) {
+  return invoke(tool.tauri, input)
+}

package/src/vue/use-agent.js

@@ -0,0 +1,57 @@
+import { fetch as tauriFetch } from '@tauri-apps/plugin-http'
+import { createAgentKit } from '../core/agent-kit.js'
+import { createOpenAiChat } from '../core/llm.js'
+import { createTauriJournalStore } from './journal-store-tauri.js'
+import { tauriTransport } from './transports.js'
+import { useOmlx } from './use-omlx.js'
+
+// In-app agent gateway: binds an app's catalog/prompt to the webview transports —
+// omlx via tauri-http, tools via Tauri invoke, journal via the tauri-plugin-agent
+// commands. Returns a flat surface the dialogs consume: request(intent),
+// respond(id, msg), approve(id, ok) plus the omlx config refs and the journal.
+//
+// Apps pass their catalog + systemPrompt (+ optional grounding/omlx defaults);
+// everything Tauri-specific is wired here so feature dialogs stay domain-free.
+
+const DEFAULT_ACTOR = { kind: 'human', id: 'local' }
+
+/**
+ * @param {object} config gateway config
+ * @param {object[]} config.catalog app tool catalog (required)
+ * @param {string|((ctx: object) => string)} [config.systemPrompt] domain prompt or builder
+ * @param {{ tool: string, key?: string, fallback?: unknown }} [config.grounding] optional prompt grounding
+ * @param {Record<string, number>} [config.actorTiers] tier overrides
+ * @param {{ kind: string, id: string }} [config.actor] caller identity (default human:local)
+ * @param {{ storagePrefix?: string, defaultBaseUrl?: string, defaultModel?: string }} [config.omlx] omlx config options
+ * @returns {object} in-app agent gateway
+ */
+export function useAgent({ catalog, systemPrompt, grounding, actorTiers, actor = DEFAULT_ACTOR, omlx } = {}) {
+  const { baseUrl, model, apiKey, save, loadEnv } = useOmlx(omlx)
+  const journal = createTauriJournalStore()
+  const kit = createAgentKit({ catalog, systemPrompt, transport: tauriTransport, journal, actorTiers, grounding })
+
+  /**
+   * Build an omlx chat fn from the current config (tauri-http transport).
+   * @returns {(req: object) => Promise<object>} chat function
+   */
+  function chat() {
+    return createOpenAiChat({
+      baseUrl: baseUrl.value,
+      model: model.value,
+      apiKey: apiKey.value || undefined,
+      fetchFn: tauriFetch,
+    })
+  }
+
+  return {
+    baseUrl,
+    model,
+    apiKey,
+    saveOmlx: save,
+    loadOmlxEnv: loadEnv,
+    journal,
+    request: intent => kit.request({ intent, actor, chat: chat() }),
+    respond: (requestId, message) => kit.respond({ requestId, message, actor, chat: chat() }),
+    approve: (requestId, approve) => kit.approve({ requestId, approve }),
+  }
+}

package/src/vue/use-omlx.js

@@ -0,0 +1,60 @@
+import { ref } from 'vue'
+import { invoke } from '@tauri-apps/api/core'
+
+// Persisted config for the local omlx server (OpenAI-compatible MLX) that drives
+// the in-app agent. The API key / base URL come from Rust (omlx_config), which
+// reads them from ~/.omlx/settings.json — the same file the omlx server uses, so
+// the config is portable between machines without env/launchd setup. baseUrl is
+// edited in the dialog and cached in localStorage; omlx_config is the default
+// when localStorage is empty. Priority for base: localStorage > omlx_config >
+// hardcoded default. The key always comes from omlx_config.
+//
+// storagePrefix namespaces the localStorage keys per app (so `task` and `mlmail`
+// keep independent base/model). defaults seed first launch.
+
+const DEFAULT_BASE_URL = 'http://127.0.0.1:8000/v1'
+
+/**
+ * @param {{ storagePrefix?: string, defaultBaseUrl?: string, defaultModel?: string }} [options] config
+ * @returns {{ baseUrl: import('vue').Ref<string>, model: import('vue').Ref<string>, apiKey: import('vue').Ref<string>, save: () => void, loadEnv: () => Promise<void> }} persisted omlx config, an env loader and a saver
+ */
+export function useOmlx({ storagePrefix = 'agent', defaultBaseUrl = DEFAULT_BASE_URL, defaultModel = '' } = {}) {
+  const baseUrlKey = `${storagePrefix}:omlxBaseUrl`
+  const modelKey = `${storagePrefix}:omlxModel`
+
+  const baseUrl = ref(localStorage.getItem(baseUrlKey) || defaultBaseUrl)
+  const model = ref(localStorage.getItem(modelKey) || defaultModel)
+  // Filled from the global env in loadEnv(); never persisted to localStorage.
+  const apiKey = ref('')
+
+  /**
+   * Pull OMLX_* from the user's global env (via Rust) and apply them: the API
+   * key is taken verbatim; baseUrl/model only fill in when localStorage is empty,
+   * so a value set in the dialog still wins. No-op outside Tauri (tests / web).
+   * @returns {Promise<void>}
+   */
+  async function loadEnv() {
+    let env
+    try {
+      env = await invoke('omlx_config')
+    }
+    catch {
+      return // not running under Tauri — keep localStorage / defaults
+    }
+    if (!env) return
+    if (env.apiKey) apiKey.value = env.apiKey
+    if (env.baseUrl && !localStorage.getItem(baseUrlKey)) baseUrl.value = env.baseUrl
+    if (env.model && !localStorage.getItem(modelKey)) model.value = env.model
+  }
+
+  /**
+   * Persist baseUrl/model to localStorage. The API key is intentionally NOT
+   * persisted — it comes from the global OMLX_API_KEY env on each launch.
+   */
+  function save() {
+    localStorage.setItem(baseUrlKey, baseUrl.value)
+    localStorage.setItem(modelKey, model.value)
+  }
+
+  return { baseUrl, model, apiKey, save, loadEnv }
+}