openvisio-agent 0.20.0 → 0.21.1

package/README.md

@@ -4,6 +4,8 @@ Connect your coding agent (**Claude Code, Codex, or OpenCode**) to an [OpenVisio
 
 **New here?** Start with the [user guide](USER_GUIDE.md) for setup, everyday work, Agent Studio, and troubleshooting.
 
+**Agent controls:** In the app, choose **Agents → Open Agent Studio**. Updated backend watchers start Studio automatically on this computer. Select an agent’s **Model settings** to change reply and coding models for the next request without a restart. Agents can offer the same button in chat; rate-limit notices link directly to settings. Model access and quota remain managed by the connected provider.
+
 ```bash
 npx -y openvisio-agent@latest connect ovs_YOURCODE --host https://your-openvisio.app --name "Ada"
 ```
@@ -138,7 +140,7 @@ npx -y openvisio-agent@latest studio
 
 To run from source, see [the checkout instructions](USER_GUIDE.md#run-studio-from-this-checkout).
 
-Select **User guide** in Studio for a local, printable guide to controls and statuses. Start with [the walkthrough](USER_GUIDE.md#open-agent-studio) if you have not used the viewer before.
+Select **Read the guide** under **Documentation** in the sidebar (or **Documentation** in the mobile header) for a local, printable guide to controls and statuses. Start with [the walkthrough](USER_GUIDE.md#open-agent-studio) if you have not used the viewer before.
 
 Studio opens `http://127.0.0.1:4317` and follows the local agents' activity live. Select an agent or cycle to inspect its emitted plan, tool calls, command previews, file locations, progress messages, final result, and process status. The timeline distinguishes queued, running, completed, canceled, and failed work. Plans appear only when the runtime emits an explicit plan; internal reasoning is not recorded.
 

package/USER_GUIDE.md

@@ -70,7 +70,9 @@ Replies stay in their source thread. New completion messages use the agent’s d
 
 ## Open Agent Studio
 
-In another terminal, using a Studio-capable installation:
+In the app, choose **Agents → Open Agent Studio**. Updated backend watchers start Studio automatically. Agent chat replies can also show this button and open the relevant agent’s settings directly.
+
+Studio manages agents on **this computer**, under your local account. It cannot change agents running on someone else’s machine. For a manual launch:
 
 ```sh
 openvisio-agent studio
@@ -91,13 +93,19 @@ The demo makes no model calls. Close it with `Ctrl+C` in its terminal and run St
 1. Select an agent in the sidebar.
 2. Select **Cycles**. A cycle is a group of actions for one unit of work.
 3. Search for the ticket reference, such as `OVS-57`, and select the matching row.
-4. Review its **Outcome**, tools, and **Final response**. Expand **Cycle history** for the recorded sequence.
+4. Switch between **Plan**, **Commands**, and **Response** to inspect steps, tool calls, and the final response. Expand **Runtime details** or **Cycle history** for more context.
 
 Use **Activity** for individual events and **Processes** for watcher and runtime records. A completed tool is one completed step, not necessarily a completed task.
 
 **Pause view** freezes the page while agents keep working. **Resume view** shows the latest available snapshot. Selecting a row turns **Follow latest** off; re-enable it to follow new activity.
 
-Select **User guide** in Studio for the full guide to controls, status meanings, keyboard navigation, history, and troubleshooting. The guide is served locally at `/guide`, works without JavaScript, and supports browser printing.
+Select **Read the guide** in the sidebar’s **Documentation** card, or **Documentation** in the mobile header, for the full guide to controls, status meanings, keyboard navigation, history, and troubleshooting. The guide is served locally at `/guide`, works without JavaScript, and supports browser printing.
+
+### Change models
+
+Select an agent → **Model settings** → choose its reply and coding models → **Save models**. OpenCode’s model choices come from its installed runtime; the fields also accept custom IDs. A listed model still needs provider access and available quota.
+
+Watchers running version **0.21.0 or newer** apply saved settings to the next request, without a restart. Current work continues with its original model. Studio distinguishes saved settings waiting for the watcher from applied choices. Offline agents keep the selection for their next connection. An older running watcher and Studio must load the update once.
 
 ### Understand what you see
 
@@ -137,7 +145,8 @@ Only new activity from an updated watcher appears in Studio. Earlier plans, tool
 | “Restart watcher to connect” | Update and restart that watcher using the steps above. |
 | No matching activity | Clear search, kind, and status filters, then select All agents. |
 | Reconnecting | Keep Studio running in its terminal. The browser automatically reconnects when the server returns. |
-| Agent is blocked | Read its outcome and ticket. Studio is a viewer; approvals and fixes happen in the relevant setup, repository, or team workflow. |
+| Agent is rate-limited | Open its **Model settings** and choose a model with available quota, or wait for the provider limit to reset. Send a new request to retry. |
+| Agent is blocked | Read its outcome and ticket. Repository approvals and fixes happen in the relevant setup, repository, or team workflow. |
 | Result is missing | Check the original ticket and channel. Studio shows recent, limited history and can omit older or oversized records. |
 
 For a macOS background service, the watcher log is at `~/.openvisio/<agent>.log`. For Linux, use `journalctl --user -u openvisio-<agent>`. Foreground watchers print to their terminal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "description": "Connect Claude Code, Codex, or OpenCode to an OpenVisio team \u2014 MCP tools + optional autonomy \u2014 in one command.",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "studio",
     "src",
     "README.md",
+    "CHANGELOG.md",
     "USER_GUIDE.md"
   ],
   "engines": {

package/scenarios/workspace.scenarios.mjs

@@ -16,7 +16,7 @@ async function eventually(predicate, description) {
   assert.fail(`Watcher did not reach: ${description}`)
 }
 
-export function fixture({ agent = 'codex', task = true, run, threadError = false, commentTools = [], onComment, selfProfile = self } = {}) {
+export function fixture({ agent = 'codex', task = true, run, threadError = false, commentTools = [], onComment, selfProfile = self, listAgents, getTicket } = {}) {
   const dir = mkdtempSync(join(tmpdir(), 'byo-workspace-'))
   const posts = [], runs = [], calls = [], logs = [], messages = [], subscriptions = []
   const ticket = { id: 77, project_id: 1, slug: 'OPEN-77', title: 'Repair the component', agent_id: 7, status: 'In Progress', type_id: 1, updated_at: 'revision-1' }
@@ -27,11 +27,11 @@ export function fixture({ agent = 'codex', task = true, run, threadError = false
     callTool: async (name, args = {}) => {
       calls.push({ name, args })
       if (commentTools.includes(name)) return onComment ? await onComment(name, args) : { id: 500 }
-      if (name === 'list_agents') return { agents: [selfProfile] }
+      if (name === 'list_agents') return listAgents ? await listAgents() : { agents: [selfProfile] }
       if (name === 'list_projects') return { projects: [{ id: 1, name: 'Workspace' }] }
       if (name === 'list_tasks') return { tasks: task ? [{ ...ticket }] : [] }
       if (name === 'list_task_types') return { types: [{ id: 1, name: 'In Progress' }, { id: 2, name: 'Testing' }, { id: 3, name: 'Done' }] }
-      if (name === 'get_ticket') { assert.equal(args.project_id, 1); assert.equal(args.ticket_id, 77); return { ticket: { ...ticket } } }
+      if (name === 'get_ticket') { assert.equal(args.project_id, 1); assert.equal(args.ticket_id, 77); return { ticket: getTicket ? getTicket(ticket) : { ...ticket } } }
       if (name === 'update_ticket') { Object.assign(ticket, args); return { ticket: { ...ticket } } }
       if (name === 'list_channels') return { channels: [{ id: 2, name: 'alex', agent_id: 7 }, { id: 9, name: 'general' }] }
       if (name === 'list_activity') return { activities: [] }

package/scripts/certify.mjs

@@ -68,7 +68,7 @@ const assertions = [
   ['prematurely acknowledged owned-thread replies recover exactly once', watcher.includes("!threadOwned || memory.has(sourceKey, 'received')") && watcher.includes('agent:mention replay recovered for active owned thread')],
   ['reconciliation recovers untagged human follow-ups in owned threads', watcher.includes("memory.has(activityControlKey, 'active')") && watcher.includes('const addressedActivity = mentionNeedles.some') && watcher.includes("memory.has(activitySourceKey, 'received')")],
   ['coding mentions require an action and concrete repository target', watcher.includes('conversationNeedsCode(text, { rootContent:') && events.includes('const action =') && events.includes('const target =')],
-  ['agent-authored roots establish ownership and legacy roots are verified before routing', watcher.includes('saveOwnThread(channelId, postedId, message)') && watcher.includes('await resolveOwnThread(cid, parent)') && watcher.includes('_threadRootContent: rootContent')],
+  ['agent-authored roots establish ownership and unaddressed legacy roots are verified before routing', watcher.includes('saveOwnThread(channelId, postedId, message)') && watcher.includes('const context = resolveOwnThread(cid, parent)') && watcher.includes('})]) : await context') && watcher.includes('_threadRootContent: rootContent')],
   ['stand-down and redirects cancel only source-thread workers', watcher.includes('cancelThread(cid, threadRoot') && watcher.includes('item.control.cancelled = true') && watcher.includes('item.control.runner?.cancelCurrent') && watcher.includes("subtype === 'canceled'")],
   ['thread cancellation is rechecked immediately before watcher delivery', watcher.includes('const newlyCancelled = suppressCancelled()') && watcher.includes('if (newlyCancelled) return newlyCancelled')],
   ['generic coding pickup messages are absent', !watcher.includes("I've picked this up and will return here with the verified result")],
@@ -137,7 +137,7 @@ const assertions = [
   ['policy blocker is surfaced to the user', watcher.includes('reportPolicyBlock(prompt, activeTaskRef, result.policyBlock, delivery)') && watcher.includes("The local runtime rejected")],
   ['blocker routing carries explicit task identity', watcher.includes('const activeTaskRef = taskRef') && watcher.includes('taskRef: activeTaskRef')],
   ['reply discovery failures stay scoped while failed mutations fail closed', watcher.includes('blockingReplyMcpErrors(result?.mcpErrors)') && watcher.includes('preserving the scoped model reply') && events.includes('export function blockingReplyMcpErrors')],
-  ['pending-ticket questions use watcher-owned MCP reads without a chat model cycle', watcher.includes('conversationAsksPendingTickets(text)') && watcher.includes('pending-ticket question -> watcher-owned MCP lookup') && watcher.includes("callMcpReadWithRetry('list_tasks'") && watcher.includes("if (selfAgentId == null) {\n      const agentsData = toolData(await callMcpReadWithRetry('list_agents'))")],
+  ['pending-ticket questions use watcher-owned MCP reads without a chat model cycle', watcher.includes('conversationAsksPendingTickets(text)') && watcher.includes('pending-ticket question -> watcher-owned MCP lookup') && watcher.includes("callMcpReadWithRetry('list_tasks'")],
   ['chat ACP allows opaque MCP approvals behind a strict read-only proxy', mastraHarness.includes('export function acpPermissionResponse') && mastraHarness.includes('opaqueMcpApproval') && mastraHarness.includes('OPENVISIO_CODEX_ALLOWED_TOOLS') && codexProxy.includes('export function toolAllowed') && codexProxy.includes('allowedTools.has(name)')],
   ['all runtime blockers have a delivery path', watcher.includes('publishBlocker') && watcher.includes('WORK_CYCLE_BLOCKED') && watcher.includes('COORDINATION_CYCLE_BLOCKED')],
   ['ticket blocker cannot self-authorize', watcher.includes("ticketNotice = `I'm paused") && watcher.includes('publishBlocker({ prompt, taskRef, delivery, notice, ticketNotice, pause: true })') && !watcher.includes('test(approvalText)')],

package/src/events.mjs

@@ -26,11 +26,15 @@ export function taskAgentId(task) {
   return task.agent_id ?? task.agentId ?? task.agent?.id ?? task.assigned_agent?.id ?? task.assignedAgent?.id ?? null
 }
 
+export function taskAgentIdentifier(task) {
+  return task?.agent_identifier ?? task?.agentIdentifier ?? task?.agent?.identifier ?? task?.agent?.slug ?? task?.assigned_agent?.identifier ?? task?.assigned_agent?.slug ?? task?.assignedAgent?.identifier ?? task?.assignedAgent?.slug ?? null
+}
+
 export function taskBelongsToAgent(task, { id, identifier } = {}) {
   if (!task || typeof task !== 'object') return false
   const assignedId = taskAgentId(task)
   if (assignedId != null && id != null) return String(assignedId) === String(id)
-  const assignedIdentifier = task.agent_identifier ?? task.agentIdentifier ?? task.agent?.identifier ?? task.agent?.slug ?? task.assigned_agent?.identifier ?? task.assigned_agent?.slug ?? task.assignedAgent?.identifier ?? task.assignedAgent?.slug
+  const assignedIdentifier = taskAgentIdentifier(task)
   return !!identifier && assignedIdentifier != null && String(assignedIdentifier) === String(identifier)
 }
 
@@ -555,12 +559,22 @@ export function conversationAsksPendingTickets(value) {
   return pending && question
 }
 
+// Filing a ticket is a team mutation, even when its description asks for code.
+// Questions about a previous creation and negated requests stay read-only.
+export function conversationCreatesTicket(value) {
+  const text = String(value || '').replace(/^@\S+\s*[,,:]?\s*/, '')
+  return text.split(/[;!?]|\b(?:but|however|instead)\b/i).some((clause) => {
+    const positive = clause.split(/\b(?:do\s+not|don't|dont|never|stop)\b/i)[0]
+    return /(?:^\s*|\bplease\s+|\b(?:can|could|would|will)\s+you\s+)(?:create|file|open|add|make)\s+(?:(?:a|an|the|new|demo|test|sample|another|one|pending|backlog)\s+){0,4}(?:ticket|task|bug|issue)\b(?!\s+(?:form|component|page|screen|endpoint|schema|template)\b)/i.test(positive)
+  })
+}
+
 // Read-only discovery failures in a reply cycle are not failed mutations and
 // must not be inflated into a generic user-facing blocker. The model can give a
 // precise, scoped answer (or say which live fact it could not read). Failed team
 // mutations remain fail-closed so prose can never masquerade as a completed act.
 export function blockingReplyMcpErrors(errors) {
-  const mutation = /^(?:update_ticket|post_message|create_task_comment|comment_ticket|react_message|create_codebase_branch|create_codebase_commit|write_codebase_file|create_pull_request)$/
+  const mutation = /^(?:create_ticket|update_ticket|post_message|create_task_comment|comment_ticket|react_message|create_codebase_branch|create_codebase_commit|write_codebase_file|create_pull_request)$/
   return [...new Set((Array.isArray(errors) ? errors : []).map((name) => String(name || '').replace(/^.*(?:__|[.:/])/, '').replace(/[-.]/g, '_').toLowerCase()).filter((name) => mutation.test(name)))]
 }
 

package/src/mastra-harness.mjs

@@ -9,7 +9,7 @@ import { buildOpencodeConfig } from './opencode-config.mjs'
 
 const MCP_TOOL_NAMES = [
   'list_agents', 'list_projects', 'list_tasks', 'list_task_types', 'get_ticket',
-  'update_ticket', 'list_channels', 'list_message_thread', 'list_activity',
+  'create_ticket', 'update_ticket', 'list_channels', 'list_message_thread', 'list_activity',
   'post_message', 'react_message', 'list_codebases', 'get_codebase',
   'codebase_tree', 'create_codebase_branch', 'create_codebase_commit',
   'create_pull_request', 'write_codebase_file', 'create_task_comment', 'comment_ticket',
@@ -19,7 +19,7 @@ const CHAT_SAFE_MCP_READS = new Set([
   'list_channels', 'list_message_thread', 'list_activity', 'list_codebases',
   'get_codebase', 'codebase_tree',
 ])
-const COORDINATION_TOOLS = ['update_ticket', 'post_message', 'react_message', 'create_task_comment', 'comment_ticket']
+const COORDINATION_TOOLS = ['create_ticket', 'update_ticket', 'post_message', 'react_message', 'create_task_comment', 'comment_ticket']
 
 const clean = (value, max = 300) => String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max)
 const json = (value) => { try { return JSON.stringify(value) } catch { return String(value ?? '') } }
@@ -38,7 +38,7 @@ async function abortable(operation, signal) {
 }
 
 function commandFor(agent) {
-  if (agent === 'opencode') return { command: onPath('opencode') || 'opencode', args: ['acp'] }
+  if (agent === 'opencode') return { command: onPath('opencode') || 'opencode', args: ['acp', '--print-logs', '--log-level', 'ERROR'] }
   if (agent === 'codex') {
     const filename = process.platform === 'win32' ? 'codex-acp.cmd' : 'codex-acp'
     return { command: fileURLToPath(new URL(`../node_modules/.bin/${filename}`, import.meta.url)), args: [] }
@@ -113,9 +113,9 @@ export function createMastraAcpRunner({
     try { Promise.resolve(onEvent?.(type, data)).catch(() => {}) } catch { /* diagnostics cannot block work */ }
   }
   const disconnect = (acp, status = 'disconnected') => {
-    acp.connection.disconnect()
     if (!disconnected.has(acp)) {
       disconnected.add(acp)
+      acp.connection.disconnect()
       lastProcessEvent?.('process.stopped', { status })
     }
   }
@@ -249,6 +249,32 @@ export function createMastraAcpRunner({
       }
     }
     const timer = setTimeout(() => { timedOut = true; controller.abort(); invalidate() }, maxCycleMs)
+    // OpenCode can keep its ACP prompt open while the provider retries a 429.
+    // Mastra 0.4.1 buffers child stderr but does not forward these diagnostics.
+    // Only recognize the current session's main model failure, never title
+    // generation, tool output, or diagnostics left over from a warm cycle.
+    let stderrOffset = String(acp.connection.stderr || '').length
+    let stderrPending = ''
+    let providerFailure = null
+    const diagnosticTimer = agent === 'opencode' ? setInterval(() => {
+      const stderr = String(acp.connection.stderr || '')
+      if (stderr.length < stderrOffset) stderrOffset = 0
+      stderrPending += stderr.slice(stderrOffset)
+      stderrOffset = stderr.length
+      const lines = stderrPending.split('\n')
+      stderrPending = lines.pop().slice(-8000)
+      const sessionId = acp.connection.sessionId
+      for (const line of lines) {
+        if (!sessionId || !line.includes(`session.id=${sessionId} `) ||
+            !line.includes('level=ERROR ') || !line.includes('message="stream error"') ||
+            !line.includes('small=false ') || !/Rate limit exceeded/i.test(line)) continue
+        providerFailure = 'OpenCode’s model provider is rate-limiting this request. Retry after the provider limit resets, or select a model with available quota using --chat-model (replies) or --model (coding).'
+        log(providerFailure)
+        controller.abort(new Error(providerFailure))
+        invalidate()
+        break
+      }
+    }, 250) : null
     const requestedModel = cycleModel || model || ''
     let selectedModel = ''
     try {
@@ -358,7 +384,7 @@ export function createMastraAcpRunner({
       }
     } catch (error) {
       const canceled = controller.signal.aborted
-      const subtype = timedOut ? 'timeout' : canceled ? 'canceled' : 'error'
+      const subtype = providerFailure ? 'rate_limited' : timedOut ? 'timeout' : canceled ? 'canceled' : 'error'
       const errorDetail = [error?.message, error?.data ? json(error.data) : ''].filter(Boolean).join(': ')
       const safeError = redact(errorDetail)
       flushProgress()
@@ -367,7 +393,7 @@ export function createMastraAcpRunner({
       log(`${agent} cycle done via Mastra ACP (${subtype}${!canceled && safeError ? ': ' + clean(safeError, 1200) : ''})`)
       invalidate()
       return {
-        type: 'result', subtype, runtime: 'mastra-acp', model: selectedModel || null, requestedModel: requestedModel || null, outputText: outputText.trim(),
+        type: 'result', subtype, userMessage: providerFailure, runtime: 'mastra-acp', model: selectedModel || null, requestedModel: requestedModel || null, outputText: outputText.trim(),
         mcpCalls: [...calls], mcpErrors: [...errors.keys()], mcpErrorDetails: Object.fromEntries(errors),
         didCode, didRepoMutation, didMessage, didChannelMessage, didResultMessage,
         didMcpTaskRead, didMcpTaskUpdate,
@@ -376,6 +402,7 @@ export function createMastraAcpRunner({
       flushProgress()
       if (!disconnected.has(acp)) emit('process.ready', { status: 'idle', sessionId: acp.connection.sessionId || null })
       clearTimeout(timer)
+      clearInterval(diagnosticTimer)
       if (active?.acp === acp) active = null
     }
   }

package/src/model-settings.mjs

@@ -0,0 +1,57 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { constants, openSync, closeSync, fstatSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { onPath } from './lib.mjs'
+
+const modelId = value => typeof value === 'string' && value.length <= 200 && /^[a-zA-Z0-9][a-zA-Z0-9_.:/+\[\]-]*$/.test(value)
+const problem = (message, status = 400) => Object.assign(new Error(message), { status })
+
+function readConfig(stateDir, slug) {
+  if (!/^[a-z0-9][a-z0-9_-]{0,79}$/i.test(slug)) throw problem('Invalid agent', 404)
+  const fd = openSync(join(stateDir, `${slug}.json`), constants.O_RDONLY | (constants.O_NOFOLLOW || 0))
+  try {
+    const stat = fstatSync(fd)
+    if (!stat.isFile() || stat.size > 64 * 1024) throw problem('Agent settings are unavailable', 404)
+    const config = JSON.parse(readFileSync(fd, 'utf8'))
+    if (config.slug !== slug || config.mode !== 'backend' || !config.identifier || !config.apiKey) throw problem('This agent does not support model settings', 404)
+    return config
+  } finally { closeSync(fd) }
+}
+
+function publicSettings(config) {
+  const model = typeof config.model === 'string' ? config.model : ''
+  const chatModel = typeof config.chatModel === 'string' ? config.chatModel : ''
+  const revision = config.modelSettingsRevision || ''
+  return { model, chatModel, revision, provider: config.agent || 'claude',
+    version: createHash('sha256').update(JSON.stringify([model, chatModel, revision])).digest('hex') }
+}
+
+export function readModelSettings(stateDir, slug) {
+  return publicSettings(readConfig(stateDir, slug))
+}
+
+export function saveModelSettings(stateDir, slug, input) {
+  if (!input || !modelId(input.model) || !modelId(input.chatModel)) throw problem('Choose a valid model for both replies and coding.')
+  const config = readConfig(stateDir, slug)
+  if (input.version !== publicSettings(config).version) throw problem('These settings changed elsewhere. Reopen model settings and try again.', 409)
+  const next = { ...config, model: input.model, chatModel: input.chatModel, modelSettingsRevision: randomUUID() }
+  const target = join(stateDir, `${slug}.json`)
+  const temporary = join(stateDir, `.${slug}-${randomUUID()}.tmp`)
+  try {
+    writeFileSync(temporary, JSON.stringify(next, null, 2) + '\n', { mode: 0o600, flag: 'wx' })
+    renameSync(temporary, target)
+  } finally { try { unlinkSync(temporary) } catch { /* already renamed */ } }
+  return publicSettings(next)
+}
+
+export async function listRuntimeModels(provider) {
+  if (provider === 'claude') return ['sonnet', 'opus', 'haiku']
+  if (provider === 'codex') return ['gpt-5.6-sol[medium]'] // Same default as the watcher; custom IDs remain available.
+  if (provider !== 'opencode') return []
+  const command = onPath('opencode')
+  if (!command) throw problem('OpenCode is not installed on this computer.', 503)
+  const { stdout } = await promisify(execFile)(command, ['models'], { timeout: 15_000, maxBuffer: 1024 * 1024, encoding: 'utf8' })
+  return [...new Set(stdout.split(/\r?\n/).map(s => s.trim()).filter(modelId))].slice(0, 1000)
+}

package/src/studio-cli.mjs

@@ -1,7 +1,18 @@
 import { spawn } from 'node:child_process'
 import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { OV_DIR } from './lib.mjs'
 
+// A separate process keeps Studio available when an individual watcher exits.
+// Concurrent watchers may race to start it; only one can bind the fixed port.
+export function startStudioInBackground({ spawnProcess = spawn } = {}) {
+  try {
+    const child = spawnProcess(process.execPath, [fileURLToPath(new URL('../bin/cli.mjs', import.meta.url)), 'studio', '--no-open'], { detached: true, stdio: 'ignore', windowsHide: true, shell: false })
+    child.once('error', () => {})
+    child.unref()
+  } catch { /* Studio availability must not prevent agent work */ }
+}
+
 export function studioOptions({ flags = {}, positional = [] } = {}) {
   const supported = new Set(['port', 'no-open', 'demo', 'state-dir'])
   if (positional.length) throw new Error('studio accepts options only. Use openvisio-agent studio --help.')

package/src/studio-server.mjs

@@ -5,6 +5,7 @@ import { createServer } from 'node:http'
 import { dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { isPrivateThoughtEvent, sanitizeJournalData } from './agent-journal.mjs'
+import { readModelSettings, saveModelSettings, listRuntimeModels } from './model-settings.mjs'
 
 const MAX_EVENTS = 500, MAX_FILES = 32, MAX_FILE_BYTES = 256 * 1024, MAX_TOTAL_BYTES = 4 * 1024 * 1024
 const FRESH_MS = 45_000
@@ -65,7 +66,7 @@ async function configuredAgents(stateDir) {
       const lock = await readSmallLocalFile(join(stateDir, `watch-${config.slug}.lock`), 64).catch(() => null)
       if (/^\d+\s*$/.test(lock || '')) { pid = Number(lock.trim()); watcherAlive = pidAlive(pid) }
       const identifier = backend ? config.identifier : config.slug
-      agents.push(sanitizeJournalData({ id: identifier, identifier, slug: config.slug, name: config.name || config.slug, provider: config.agent || 'claude', configured: true, runId: null, pid, watcherAlive, status: 'uninstrumented', lastSeen: null, lastEventType: null }))
+      agents.push(sanitizeJournalData({ id: identifier, identifier, slug: config.slug, name: config.name || config.slug, provider: config.agent || 'claude', configured: true, settingsEditable: !!backend, modelSettings: backend ? readModelSettings(stateDir, config.slug) : null, runId: null, pid, watcherAlive, status: 'uninstrumented', lastSeen: null, lastEventType: null }))
     } catch { /* unrelated, malformed or concurrently replaced setup file */ }
   }
   return agents
@@ -107,6 +108,11 @@ export async function readStudioSnapshot({ stateDir, now = Date.now }) {
     agentsById.set(event.agent.identifier, { ...existing, id: event.agent.identifier, identifier: event.agent.identifier, slug: event.agent.slug || event.agent.identifier, name: existing?.name || event.agent.slug || event.agent.identifier, provider: event.agent.provider || 'unknown', runId: event.runId, pid: Number.isSafeInteger(event.pid) ? event.pid : null, watcherAlive: online, status: online ? 'online' : 'offline', lastSeen: event.timestamp, lastEventType: event.type })
   }
   const agents = [...agentsById.values()].sort((a, b) => a.name.localeCompare(b.name))
+  for (const agent of agents) {
+    const applied = events.findLast(event => event.agent.identifier === agent.identifier && event.runId === agent.runId && typeof event.data?.modelSettingsRevision === 'string')
+    agent.appliedModelRevision = applied?.data.modelSettingsRevision || ''
+    agent.modelControlsSupported = !!applied
+  }
   return { schemaVersion: 1, demo: false, generatedAt: new Date(now()).toISOString(), agents, events: events.slice(-MAX_EVENTS), limits: { maxEvents: MAX_EVENTS, maxFiles: MAX_FILES, maxTotalBytes: MAX_TOTAL_BYTES }, warnings }
 }
 
@@ -135,13 +141,14 @@ function demoSnapshot(stamp) {
   return { schemaVersion: 1, demo: true, generatedAt: new Date(stamp).toISOString(), agents, events: events.sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp)), limits: { maxEvents: MAX_EVENTS }, warnings: ['Demo mode contains simulated agent activity. No model or task is running.'] }
 }
 
-export async function startStudioServer({ stateDir, host = '127.0.0.1', port = 4317, assetsDir = DEFAULT_ASSETS, demo = false }) {
+export async function startStudioServer({ stateDir, host = '127.0.0.1', port = 4317, assetsDir = DEFAULT_ASSETS, demo = false, modelCatalog = listRuntimeModels }) {
   if (!['127.0.0.1', '::1', 'localhost'].includes(host)) throw new Error('Agent Studio can bind only to a loopback address')
   if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Agent Studio port must be an integer from 0 to 65535')
   if (!stateDir) throw new Error('Agent Studio requires a local state directory')
   const bindHost = host === 'localhost' ? '127.0.0.1' : host
   const root = await realpath(assetsDir)
   const clients = new Set()
+  const catalogs = new Map()
   const demoState = demo ? demoSnapshot(Date.now()) : null
   let current, pending, stopped = false, interval
   const delivered = new WeakMap()
@@ -170,11 +177,40 @@ export async function startStudioServer({ stateDir, host = '127.0.0.1', port = 4
     try {
       const boundPort = server.address().port
       const allowedAuthorities = new Set([`127.0.0.1:${boundPort}`, `localhost:${boundPort}`, `[::1]:${boundPort}`])
+      const path = new URL(req.url, `http://${req.headers.host}`).pathname
       if (!allowedAuthorities.has(String(req.headers.host || '').toLowerCase())) { res.writeHead(403); res.end('Invalid local host'); return }
       if (req.headers.origin && ![...allowedAuthorities].some((authority) => req.headers.origin === `http://${authority}`)) { res.writeHead(403); res.end('Cross-origin access denied'); return }
-      if (req.headers['sec-fetch-site'] === 'cross-site') { res.writeHead(403); res.end('Cross-site access denied'); return }
-      if (!['GET', 'HEAD'].includes(req.method)) { res.writeHead(405, { allow: 'GET, HEAD' }); res.end('Read-only viewer'); return }
-      const path = new URL(req.url, `http://${req.headers.host}`).pathname
+      const studioNavigation = req.method === 'GET' && path === '/' && req.headers['sec-fetch-mode'] === 'navigate' && req.headers['sec-fetch-dest'] === 'document'
+      if (req.headers['sec-fetch-site'] === 'cross-site' && !studioNavigation) { res.writeHead(403); res.end('Cross-site access denied'); return }
+      const settingsRoute = /^\/api\/agents\/([a-z0-9][a-z0-9_-]{0,79})\/(models|settings)$/i.exec(path)
+      if (settingsRoute && !demo) {
+        const [, slug, action] = settingsRoute
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        try {
+          const settings = readModelSettings(stateDir, slug)
+          if (req.method === 'GET') {
+            if (action === 'settings') { res.end(JSON.stringify(settings)); return }
+            if (!catalogs.has(settings.provider)) {
+              const catalog = Promise.resolve().then(() => modelCatalog(settings.provider)).finally(() => catalogs.delete(settings.provider))
+              catalogs.set(settings.provider, catalog)
+            }
+            res.end(JSON.stringify({ models: await catalogs.get(settings.provider) })); return
+          }
+          if (req.method === 'POST' && action === 'settings') {
+            if (req.headers.origin !== `http://${req.headers.host}` || req.headers['content-type']?.split(';')[0] !== 'application/json') { res.writeHead(403); res.end(JSON.stringify({ error: 'Use the local Studio page to change settings.' })); return }
+            let body = ''
+            for await (const chunk of req) { body += chunk; if (Buffer.byteLength(body) > 4096) throw Object.assign(new Error('Settings request is too large'), { status: 413 }) }
+            let input
+            try { input = JSON.parse(body) } catch { throw Object.assign(new Error('Invalid settings request'), { status: 400 }) }
+            res.end(JSON.stringify(saveModelSettings(stateDir, slug, input))); return
+          }
+          res.writeHead(405); res.end(JSON.stringify({ error: 'Method not allowed' })); return
+        } catch (error) {
+          res.writeHead(error.status || (error.code === 'ENOENT' || error.code === 'ELOOP' ? 404 : 503))
+          res.end(JSON.stringify({ error: error.status ? error.message : 'Could not load local model settings. Check that the agent runtime is installed and try again.' })); return
+        }
+      }
+      if (!['GET', 'HEAD'].includes(req.method)) { res.writeHead(405, { allow: 'GET, HEAD' }); res.end('Method not allowed'); return }
       if (path === '/api/snapshot') { res.setHeader('content-type', 'application/json; charset=utf-8'); res.end(req.method === 'HEAD' ? undefined : JSON.stringify(await snapshot())); return }
       if (path === '/api/events' && req.method === 'GET') {
         if (clients.size >= 32) { res.writeHead(503); res.end('Too many local viewer connections'); return }
@@ -183,13 +219,13 @@ export async function startStudioServer({ stateDir, host = '127.0.0.1', port = 4
         sendSnapshot(res, await snapshot())
         return
       }
-      const file = ({ '/': 'index.html', '/index.html': 'index.html', '/guide': 'guide.html', '/guide.html': 'guide.html', '/style.css': 'style.css', '/app.mjs': 'app.mjs' })[path]
+      const file = ({ '/': 'index.html', '/index.html': 'index.html', '/guide': 'guide.html', '/guide.html': 'guide.html', '/style.css': 'style.css', '/app.mjs': 'app.mjs', '/satoshi-400.woff2': 'satoshi-400.woff2', '/satoshi-500.woff2': 'satoshi-500.woff2', '/openvisio.svg': 'openvisio.svg' })[path]
       if (!file) { res.writeHead(404); res.end('Not found'); return }
       const target = await realpath(resolve(root, file))
       const rel = relative(root, target)
       if (rel.startsWith('..') || resolve(dirname(target)) !== root) { res.writeHead(403); res.end('Invalid asset'); return }
       const body = await readFile(target)
-      res.setHeader('content-type', file.endsWith('.css') ? 'text/css; charset=utf-8' : file.endsWith('.mjs') ? 'text/javascript; charset=utf-8' : 'text/html; charset=utf-8')
+      res.setHeader('content-type', file.endsWith('.svg') ? 'image/svg+xml' : file.endsWith('.woff2') ? 'font/woff2' : file.endsWith('.css') ? 'text/css; charset=utf-8' : file.endsWith('.mjs') ? 'text/javascript; charset=utf-8' : 'text/html; charset=utf-8')
       res.end(req.method === 'HEAD' ? undefined : body)
     } catch (error) {
       if (!res.headersSent) res.writeHead(error.code === 'ENOENT' ? 404 : 500)