openvisio-agent 0.25.18 → 0.25.19

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.25.19] — 2026-10-06
+
+- Add Studio **Update connection** with discovery, a review of changed endpoints, and a pasted connection-object fallback. Verify saved credentials before saving, preserve agent settings, and restart the watcher after applying. Reject stale previews and updates during recorded active work; report restart failures separately from successful saves.
+- Recover guarded channel and task-comment replies after recognized runtime transport interruptions, using the existing bounded backoff, cancellation, and single-delivery controls.
+- Classify OpenCode provider failures carried in structured ACP error data, including quota, authentication, and unavailable-model errors. Unknown failures point to the local Studio process error without publishing raw diagnostics.
+- Include Studio credential-object import, task-comment project resolution, and explicit backend migration fixes.
+- Live smoke gate waived: no designated safe test organization/ticket is available. Real provider execution and Bard/Hindris behavior remain unverified. Automatic discovery requires the deployed app route; use the pasted connection-object fallback while it is unavailable.
+
 ## [0.25.18] — 2026-10-05
 
 - Add `update --name <agent>` to fetch current connection URLs from agent setup without re-entering credentials. Support `--host` for the stable app address, manual URL overrides, and an optional background watcher restart.

package/README.md

@@ -1,6 +1,6 @@
 # openvisio-agent
 
-Connect your coding agent (**Claude Code, Codex, OpenCode, Gemini CLI, or Qwen Code**) to an [OpenVisio](https://openvisio.app) team — in one command. No shell scripts, no `curl | bash`.
+Connect your coding agent (**Claude Code, Codex, OpenCode, Gemini CLI, or Qwen Code**) to an [OpenVisio](https://openvisio.io) team — in one command. No shell scripts, no `curl | bash`.
 
 **New here?** Start with the [user guide](USER_GUIDE.md) for setup, everyday work, Agent Studio, and troubleshooting.
 
@@ -66,7 +66,7 @@ If the old connections remain healthy, an endpoint change is picked up on the ne
 
 When URLs change, the watcher saves them, reconnects its WebSocket, and uses the new MCP endpoint for new runtime sessions. Active sessions finish before being retired; they can still encounter errors if their old MCP endpoint is removed during a turn. There is no automatic process restart or cancellation of accepted work. Credentials, runtime, models, workspace, and other settings are preserved.
 
-New setup commands and copied Studio credentials include the app address. For self-hosted or staging setups, pass `--host <app-url>` to `connect`. Legacy configurations try `https://openvisio.app`, but reject a different backend. Existing agents need this package version installed and their watcher restarted once. To set a different discovery host and refresh immediately:
+New setup commands and copied Studio credentials include the app address. For self-hosted or staging setups, pass `--host <app-url>` to `connect`. Legacy configurations try `https://openvisio.io`, but reject a different backend. Existing agents need this package version installed and their watcher restarted once. To set a different discovery host and refresh immediately:
 
 ```bash
 npx -y openvisio-agent@latest update --name ada \
@@ -75,6 +75,8 @@ npx -y openvisio-agent@latest update --name ada \
 
 After the host is saved, `openvisio-agent update --name ada` fetches the current URLs without requiring either URL or another API key. Automatic refresh updates the watcher's scoped MCP configuration; the explicit `update` command also refreshes Claude's global registration when the MCP URL changes. Manual `--ws` and/or `--mcp-url` overrides remain available. Relay agents support manual MCP updates only.
 
+If the API backend itself has moved, pass `--backend <new-api-url>` along with the current `--ws <new-websocket-url>` (and `--mcp-url` if it changed). The update verifies the saved credentials against the new API before saving, preserves agent settings, and updates both API and WebSocket values in the agent's environment file. Without manual connection URLs, it discovers them from `--host` and requires that metadata to match the explicitly selected backend. Automatic discovery never migrates credentials to a different backend.
+
 `--restart` explicitly stops the named watcher (interrupting active work) and installs/starts its background service on macOS or Linux. It does not upgrade an existing global package; install the new release first. Omit it to save changes without interrupting work. Foreground watchers can be stopped and started with `openvisio-agent watch --name ada`. Explicit URL overrides on `watch` disable discovery for that invocation. The discovery app host must remain reachable; changing that host or the backend identity requires an explicit update/reconnect.
 
 ### `watch --name <agent>`

package/USER_GUIDE.md

@@ -35,9 +35,11 @@ npm install -g openvisio-agent@latest
 
 1. In OpenVisio, open **Agents** and choose the connection flow for your agent.
 2. Select your coding runtime, register the agent, and choose **Copy credentials**. The API key is shown only once.
-3. Open Agent Studio on your computer (`openvisio-agent studio`), choose **Connect agent**, and paste the credentials. You can also enter the fields individually.
+3. Open Agent Studio on your computer (`openvisio-agent studio`), choose **Connect agent**, and paste the generated JSON object. Choose **Use credentials** to review the fields, or **Verify and connect** to import and connect directly. You can also enter the fields individually.
 4. Choose **Verify and connect**. Studio checks the key and identifier and saves the connection privately on this computer. Install and sign in to your selected coding runtime, then select the agent and choose **Start watcher**.
 
+Studio retrieves missing MCP and WebSocket URLs from the OpenVisio app URL. If discovery is unavailable, enter those URLs manually; existing entered values are preserved.
+
 **Terminal option:** Expand **Or use a terminal command** in OpenVisio and run the supplied command. This remains available for CLI setup and advanced options. Existing agents can copy connection details from their profile and enter their previously saved API key in Studio.
 
 Treat copied credentials and setup commands as private. Studio does not retrieve a lost API key. Keep your one-time key somewhere safe before leaving the registration screen.
@@ -46,6 +48,14 @@ Coding mode is enabled by default for backend connections. The agent can handle
 
 For advanced connection options, see the [command reference](README.md#what-it-does).
 
+## Update an existing connection
+
+Select an agent in Studio and choose **Update connection**. Studio checks the saved OpenVisio app address for current connection URLs. Review the URLs, then choose **Apply and reconnect** to verify the saved credentials, save the settings, and restart the watcher.
+
+If the check fails, paste the latest connection JSON object from OpenVisio and choose **Check connection**. Only connection URLs are imported; the agent keeps its saved API key, identity, models, and workspace. Finish or stop active work before applying. If Studio cannot restart the watcher, it reports that the settings were saved and asks you to restart it manually.
+
+This control requires a package version containing the connection-update feature. Automatic discovery also requires the OpenVisio app to serve `/api/agent/setup/connection`; pasting the object works when discovery is unavailable.
+
 ## Start your watcher
 
 A **watcher** is the local program that listens for messages and assignments and runs your agent when there is work to do. Starting it can pick up existing assignments immediately.

package/bin/cli.mjs

@@ -29,7 +29,7 @@ Usage:
   openvisio-agent connect --backend <url> --key <api-key> --id <identifier> [--name "<agent>"] [--host <app-url>] [--ws <wss-url>] [--mcp-url <url>] [--agent ${supportedRuntimeList('|')}]
   openvisio-agent watch   --name <agent> [--install] [--workspace <dir>] [--chat-only] [--model <m>] [--chat-model <m>] [--debug]
   openvisio-agent stop    --name <agent>
-  openvisio-agent update  --name <agent> [--host <app-url>] [--ws <wss-url>] [--mcp-url <url>] [--restart]
+  openvisio-agent update  --name <agent> [--host <app-url>] [--backend <url>] [--ws <wss-url>] [--mcp-url <url>] [--restart]
   openvisio-agent studio  [--port <number>] [--no-open] [--demo]
   openvisio-agent authorize-pr-push [--repo <dir>]
   openvisio-agent push-pr-branch
@@ -82,9 +82,10 @@ watch
 
 update
   Fetches current connection URLs from agent setup, preserving credentials and
-  settings. --host selects the OpenVisio app (default: https://openvisio.app).
+  settings. --host selects the OpenVisio app (default: https://openvisio.io).
   Watchers refresh at startup and after connection failures, with no periodic poll.
   Explicit --ws/--mcp-url values remain available for manual updates.
+  Use --backend to migrate to a new API URL after verifying saved credentials.
   Restart the watcher to apply changes. --restart stops the named watcher and
   installs/starts its background service (macOS/Linux; interrupts active work).
 
@@ -220,7 +221,7 @@ async function runConnect({ positional, flags }) {
 async function runConnectBackend({ flags }) {
   const backend = stripSlash(String(flags.backend))
   const { endpoint } = await import('../src/update.mjs')
-  const setupHost = flags.host === undefined ? 'https://openvisio.app' : endpoint(flags.host, 'host', ['http:', 'https:'])
+  const setupHost = flags.host === undefined ? 'https://openvisio.io' : endpoint(flags.host, 'host', ['http:', 'https:'])
   const apiKey = flags.key && String(flags.key)
   const identifier = flags.id && String(flags.id)
   if (!/^https?:\/\//.test(backend)) fail('The --backend value must be a full URL (e.g. https://api.your-org.example/dev).')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.25.18",
+  "version": "0.25.19",
   "description": "Connect Claude Code, Codex, OpenCode, Gemini CLI, or Qwen Code to an OpenVisio team \u2014 MCP tools + optional autonomy \u2014 in one command.",
   "type": "module",
   "bin": {

package/src/connection-discovery.mjs

@@ -1,4 +1,4 @@
-export const DEFAULT_SETUP_HOST = 'https://openvisio.app'
+export const DEFAULT_SETUP_HOST = 'https://openvisio.io'
 
 // Public deployment metadata. Discovery never sends agent credentials and must
 // match the saved backend before its endpoints can receive those credentials.
@@ -11,18 +11,34 @@ function checkedUrl(value, protocols) {
   return url.href.replace(/\/+$/, '')
 }
 
-export async function fetchConnectionSettings(saved, { fetchImpl = fetch, signal } = {}) {
-  if (saved.mode !== 'backend') throw new Error('Automatic connection discovery requires a backend agent.')
-  const setupHost = checkedUrl(saved.setupHost || DEFAULT_SETUP_HOST, ['https:', 'http:'])
-  const backend = checkedUrl(saved.backend, ['https:', 'http:'])
+export function validateConnectionManifest(data) {
+  return {
+    setupHost: checkedUrl(data.setupHost || DEFAULT_SETUP_HOST, ['https:', 'http:']),
+    backend: checkedUrl(data.backend, ['https:', 'http:']),
+    wsUrl: checkedUrl(data.wsUrl, ['wss:', 'ws:']),
+    mcpUrl: checkedUrl(data.mcpUrl, ['https:', 'http:']),
+  }
+}
+
+export async function fetchConnectionManifest(host, { fetchImpl = fetch, signal } = {}) {
+  const setupHost = checkedUrl(host || DEFAULT_SETUP_HOST, ['https:', 'http:'])
   const response = await fetchImpl(`${setupHost}/api/agent/setup/connection`, {
     headers: { accept: 'application/json' }, cache: 'no-store', redirect: 'error',
     signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
   })
   if (!response.ok) { await response.body?.cancel(); throw new Error(`Connection discovery returned HTTP ${response.status}. Saved URLs are unchanged.`) }
   const data = await response.json()
-  if (data?.version !== 1 || checkedUrl(data.backend, ['https:', 'http:']) !== backend) throw new Error('Setup configuration does not match the saved backend. Use --host with this agent’s OpenVisio app URL.')
-  return { setupHost, wsUrl: checkedUrl(data.wsUrl, ['wss:', 'ws:']), mcpUrl: checkedUrl(data.mcpUrl, ['https:', 'http:']) }
+  if (data?.version !== 1) throw new Error('Unsupported connection configuration version.')
+  return validateConnectionManifest({ ...data, setupHost })
+}
+
+export async function fetchConnectionSettings(saved, options = {}) {
+  if (saved.mode !== 'backend') throw new Error('Automatic connection discovery requires a backend agent.')
+  const backend = checkedUrl(saved.backend, ['https:', 'http:'])
+  const next = await fetchConnectionManifest(saved.setupHost, options)
+  if (next.backend !== backend) throw new Error('Setup configuration does not match the saved backend. Use --host with this agent’s OpenVisio app URL.')
+  const { backend: _, ...settings } = next
+  return settings
 }
 
 // Checks run only when requested by startup, failures, or an explicit command.

package/src/mastra-harness.mjs

@@ -450,7 +450,7 @@ export function createMastraAcpRunner({
     } catch (error) {
       if (!controller.signal.aborted) {
         inspectDiagnostics(true)
-        if (agent === 'opencode') providerFailure ||= opencodeProviderFailure(error?.message)
+        if (agent === 'opencode') providerFailure ||= opencodeProviderFailure(error)
       }
       const canceled = controller.signal.aborted
       const subtype = providerFailure?.subtype || (timedOut ? 'timeout' : canceled ? 'canceled' : 'error')
@@ -463,7 +463,7 @@ export function createMastraAcpRunner({
       log(`${agent} cycle done via Mastra ACP (${subtype}${!canceled && safeError ? ': ' + clean(safeError, 1200) : ''})`)
       invalidate()
       return {
-        type: 'result', subtype, transportInterrupted: subtype === 'error' && isTransportInterruption(error), userMessage: providerFailure?.userMessage || null, runtime: 'mastra-acp', model: selectedModel || null, requestedModel: requestedModel || null, outputText: outputText.trim(),
+        type: 'result', subtype, transportInterrupted: subtype === 'error' && isTransportInterruption(error), userMessage: providerFailure?.userMessage || (agent === 'opencode' && subtype === 'error' ? 'OpenCode could not finish the request. Open the failed cycle in Agent Studio and check its process error for the runtime or provider failure before retrying.' : null), 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,

package/src/opencode-failure.mjs

@@ -1,6 +1,22 @@
 // Classify runtime diagnostics only, never assistant prose or tool output.
 export function opencodeProviderFailure(value) {
-  const text = String(value || '').split('ACP agent stderr:')[0]
+  const seen = new Set()
+  const diagnostic = (item, depth = 0) => {
+    if (item == null || depth > 6 || seen.has(item)) return ''
+    if (typeof item === 'string') {
+      const text = item.split('ACP agent stderr:')[0].slice(0, 16000)
+      try { return diagnostic(JSON.parse(text), depth + 1) } catch { return text }
+    }
+    if (typeof item !== 'object') return String(item)
+    seen.add(item)
+    // ACP commonly wraps a provider error in data under "Internal error".
+    // Read diagnostic fields only; never inspect prompts, tool output, or headers.
+    return [
+      ...['name', 'message', 'code', 'data', 'error', 'cause'].map(key => diagnostic(item[key], depth + 1)),
+      ...['status', 'statusCode', 'status_code'].filter(key => item[key] != null).map(key => `status ${item[key]}`),
+    ].join(' ')
+  }
+  const text = diagnostic(value)
   if (/rate[_ -]?limit|too many requests|\b(?:HTTP|status(?: code)?)\s*[:=]?\s*429\b/i.test(text)) {
     return { subtype: 'rate_limited', userMessage: 'OpenCode’s model provider is rate-limiting this request. Retry after the provider limit resets, or select a model with available quota in Agent Studio.' }
   }

package/src/studio-connect.mjs

@@ -2,6 +2,7 @@ import { mkdir, open, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
 import { slugify } from './lib.mjs'
 import { runtimeProvider } from './runtime-providers.mjs'
+import { fetchConnectionSettings } from './connection-discovery.mjs'
 
 const problem = (message, status = 400) => Object.assign(new Error(message), { status })
 
@@ -23,9 +24,18 @@ export async function connectStudioAgent({ stateDir, input, fetchImpl = fetch })
   const agent = field('agent')
   if (!runtimeProvider(agent)) throw problem('Choose a supported runtime.')
   const backend = url('backend', ['https:', 'http:'])
-  const mcpUrl = url('mcpUrl', ['https:', 'http:'])
-  const wsUrl = url('wsUrl', ['wss:', 'ws:'])
-  const setupHost = field('setupHost', false) ? url('setupHost', ['https:', 'http:']) : 'https://openvisio.app'
+  let mcpUrl = field('mcpUrl', false) ? url('mcpUrl', ['https:', 'http:']) : ''
+  let wsUrl = field('wsUrl', false) ? url('wsUrl', ['wss:', 'ws:']) : ''
+  const setupHost = field('setupHost', false) ? url('setupHost', ['https:', 'http:']) : 'https://openvisio.io'
+  if (!mcpUrl || !wsUrl) {
+    try {
+      const discovered = await fetchConnectionSettings({ mode: 'backend', backend, setupHost }, { fetchImpl })
+      mcpUrl ||= discovered.mcpUrl
+      wsUrl ||= discovered.wsUrl
+    } catch {
+      throw problem('Could not discover the missing connection URLs. Check the OpenVisio app URL, or enter the MCP and WebSocket URLs manually.', 502)
+    }
+  }
   let response
   try {
     response = await fetchImpl(`${backend}/projects`, { headers: { accept: 'application/json', 'x-agent-api-key': apiKey, 'x-agent-identifier': identifier }, redirect: 'error', signal: AbortSignal.timeout(15000) })

package/src/studio-connection.mjs

@@ -0,0 +1,52 @@
+import { constants, openSync, readFileSync, fstatSync, closeSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { join } from 'node:path'
+import { DEFAULT_SETUP_HOST, fetchConnectionManifest, validateConnectionManifest } from './connection-discovery.mjs'
+import { saveConnectionSettings } from './update.mjs'
+
+const problem = (message, status = 400) => Object.assign(new Error(message), { status })
+const version = (saved, settings) => createHash('sha256').update(JSON.stringify({ saved, settings })).digest('hex')
+function readConnection(stateDir, slug) {
+  if (!/^[a-z0-9][a-z0-9_-]{0,79}$/i.test(slug)) throw problem('Invalid agent.')
+  const fd = openSync(join(stateDir, `${slug}.json`), constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    if (!fstatSync(fd).isFile() || fstatSync(fd).size > 65536) throw problem('Agent settings are unavailable.')
+    const saved = JSON.parse(readFileSync(fd, 'utf8'))
+    if (saved.mode !== 'backend' || saved.slug !== slug || !saved.apiKey || !saved.identifier) throw problem('This agent does not support connection updates.')
+    return saved
+  } finally { closeSync(fd) }
+}
+
+export async function previewStudioConnection({ stateDir, slug, input = {}, fetchImpl = fetch }) {
+  const saved = readConnection(stateDir, slug)
+  const setupHost = input.setupHost || (saved.setupHost === 'https://openvisio.app' ? DEFAULT_SETUP_HOST : saved.setupHost) || DEFAULT_SETUP_HOST
+  let settings
+  try {
+    settings = input.settings
+      ? validateConnectionManifest({ ...input.settings, setupHost: input.settings.setupHost || setupHost })
+      : await fetchConnectionManifest(setupHost, { fetchImpl })
+  } catch {
+    throw problem('Could not load current connection URLs. Check the app URL, or paste the latest connection object from OpenVisio and choose Check connection.', 502)
+  }
+  return { settings, version: version(saved, settings), backendChanged: saved.backend !== settings.backend }
+}
+
+export async function applyStudioConnection({ stateDir, slug, input, fetchImpl = fetch }) {
+  const saved = readConnection(stateDir, slug)
+  let settings
+  try { settings = validateConnectionManifest(input?.settings) } catch { throw problem('Check the connection settings before applying them.') }
+  if (!input.version || input.version !== version(saved, settings)) throw problem('Agent settings changed. Check the connection again before applying.', 409)
+  let response
+  try {
+    response = await fetchImpl(`${settings.backend}/projects`, {
+      headers: { accept: 'application/json', 'x-agent-api-key': saved.apiKey, 'x-agent-identifier': saved.identifier },
+      redirect: 'error', signal: AbortSignal.timeout(15000),
+    })
+  } catch { throw problem('Could not reach the selected backend. Saved settings are unchanged.', 502) }
+  await response.body?.cancel()
+  if (!response.ok) throw problem(`The selected backend rejected verification (HTTP ${response.status}). Saved settings are unchanged.`, 502)
+  const current = readConnection(stateDir, slug)
+  if (version(current, settings) !== input.version) throw problem('Agent settings changed during verification. Check the connection again.', 409)
+  saveConnectionSettings({ stateDir, slug, saved: current, next: { ...current, ...settings } })
+  return { saved: true }
+}

package/src/studio-server.mjs

@@ -9,6 +9,8 @@ import { readModelSettings, saveModelSettings, listRuntimeModels } from './model
 import { planAgentRemoval, removeLocalAgent } from './agent-removal.mjs'
 import { controlLocalWatcher } from './watcher-control.mjs'
 import { connectStudioAgent } from './studio-connect.mjs'
+import { previewStudioConnection, applyStudioConnection } from './studio-connection.mjs'
+import { deriveModel } from '../studio/app.mjs'
 import { OV_DIR } from './lib.mjs'
 
 const MAX_EVENTS = 500, MAX_FILES = 32, MAX_FILE_BYTES = 256 * 1024, MAX_TOTAL_BYTES = 4 * 1024 * 1024
@@ -164,7 +166,7 @@ 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, modelCatalog = listRuntimeModels, removeAgent = removeLocalAgent, watcherControl = controlLocalWatcher, connectAgent = connectStudioAgent }) {
+export async function startStudioServer({ stateDir, host = '127.0.0.1', port = 4317, assetsDir = DEFAULT_ASSETS, demo = false, modelCatalog = listRuntimeModels, removeAgent = removeLocalAgent, watcherControl = controlLocalWatcher, connectAgent = connectStudioAgent, previewConnection = previewStudioConnection, applyConnection = applyStudioConnection }) {
   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')
@@ -227,6 +229,39 @@ export async function startStudioServer({ stateDir, host = '127.0.0.1', port = 4
         }
         return
       }
+      const connectionRoute = /^\/api\/agents\/([a-z0-9][a-z0-9_-]{0,79})\/connection$/i.exec(path)
+      if (connectionRoute) {
+        const slug = connectionRoute[1]
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        try {
+          if (demo) throw Object.assign(new Error('Connection updates are unavailable in demo mode.'), { status: 403 })
+          if (req.method !== 'POST') throw Object.assign(new Error('Method not allowed'), { status: 405 })
+          if (req.headers.origin !== `http://${req.headers.host}` || req.headers['content-type']?.split(';')[0] !== 'application/json') throw Object.assign(new Error('Use the local Studio page to update connections.'), { status: 403 })
+          let body = ''
+          for await (const chunk of req) { body += chunk; if (Buffer.byteLength(body) > 16384) throw Object.assign(new Error('Connection request is too large.'), { status: 413 }) }
+          let input
+          try { input = JSON.parse(body) } catch { throw Object.assign(new Error('Invalid connection request.'), { status: 400 }) }
+          if (input?.action === 'check') { res.end(JSON.stringify(await previewConnection({ stateDir, slug, input }))); return }
+          if (input?.action !== 'apply') throw Object.assign(new Error('Choose check or apply.'), { status: 400 })
+          if (watcherChanges.has(slug) || removals.has(slug)) throw Object.assign(new Error('Another agent change is in progress.'), { status: 409 })
+          watcherChanges.add(slug)
+          try {
+            const model = deriveModel(await readStudioSnapshot({ stateDir, journalCache }))
+            if (model.cycles.some(cycle => cycle.agent?.slug === slug && ['active', 'queued', 'connecting', 'recovering'].includes(cycle.status))) throw Object.assign(new Error('This agent has active work. Finish or stop its work before applying and reconnecting.'), { status: 409 })
+            const result = await applyConnection({ stateDir, slug, input })
+            try {
+              await watcherControl({ stateDir, slug, action: 'restart' })
+              res.end(JSON.stringify({ ...result, restarted: true, message: 'Connection settings saved and watcher restarted. Check its activity for connection status.' }))
+            } catch {
+              res.end(JSON.stringify({ ...result, restarted: false, message: 'Connection settings saved, but the watcher could not restart. Start or restart it manually to apply the update.' }))
+            }
+          } finally { watcherChanges.delete(slug) }
+        } catch (error) {
+          res.writeHead(error.status || 503)
+          res.end(JSON.stringify({ error: error.status ? error.message : 'Could not update this agent connection. Check its saved configuration and try again.' }))
+        }
+        return
+      }
       const removalRoute = /^\/api\/agents\/([a-z0-9][a-z0-9_-]{0,79})\/removal$/i.exec(path)
       if (removalRoute && !demo) {
         const slug = removalRoute[1]

package/src/update.mjs

@@ -16,8 +16,8 @@ export function endpoint(value, flag, protocols) {
 }
 
 export async function runUpdate({ flags, positional = [] }) {
-  const allowed = new Set(['name', 'ws', 'mcp-url', 'restart', 'host'])
-  if (positional.length || Object.keys(flags).some(key => !allowed.has(key))) throw new Error('Usage: openvisio-agent update --name <agent> [--host <app-url>] [--ws <url>] [--mcp-url <url>] [--restart]')
+  const allowed = new Set(['name', 'ws', 'mcp-url', 'restart', 'host', 'backend'])
+  if (positional.length || Object.keys(flags).some(key => !allowed.has(key))) throw new Error('Usage: openvisio-agent update --name <agent> [--host <app-url>] [--backend <url>] [--ws <url>] [--mcp-url <url>] [--restart]')
   if (typeof flags.name !== 'string' || !flags.name.trim()) throw new Error('Missing --name <agent>.')
   if (flags.restart !== undefined && flags.restart !== true) throw new Error('--restart does not take a value.')
   if (flags.restart && process.platform === 'win32') throw new Error('--restart requires macOS or Linux. Omit it and restart the foreground watcher yourself.')
@@ -26,17 +26,38 @@ export async function runUpdate({ flags, positional = [] }) {
   if (!saved || typeof saved !== 'object' || Array.isArray(saved)) throw new Error(`No readable configuration for "${slug}". Run connect first.`)
   if (flags.ws !== undefined && saved.mode !== 'backend') throw new Error('--ws is supported only for backend agents.')
   let next = { ...saved }
+  if (flags.backend !== undefined) {
+    if (saved.mode !== 'backend') throw new Error('--backend is supported only for backend agents.')
+    next.backend = stripSlash(endpoint(flags.backend, 'backend', ['https:', 'http:']))
+    const target = new URL(next.backend)
+    if (target.search || (target.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(target.hostname))) throw new Error('--backend requires HTTPS (or local HTTP), without a query.')
+  }
   if (flags.host !== undefined) next.setupHost = endpoint(flags.host, 'host', ['http:', 'https:'])
   if (flags.ws === undefined && flags['mcp-url'] === undefined) {
     const discovered = await fetchConnectionSettings(next)
-    const current = readConfig(slug)
-    if (!current || current.apiKey !== saved.apiKey || current.identifier !== saved.identifier || current.backend !== saved.backend) throw new Error('Saved agent identity changed during discovery; retry the update.')
-    saved = current
-    next = { ...current, ...discovered }
+    next = { ...next, ...discovered }
   }
   if (flags.ws !== undefined) next.wsUrl = stripSlash(endpoint(flags.ws, 'ws', ['ws:', 'wss:']))
   if (flags['mcp-url'] !== undefined) next.mcpUrl = endpoint(flags['mcp-url'], 'mcp-url', ['http:', 'https:'])
 
+  if (next.backend !== saved.backend) {
+    // Only an explicit --backend may migrate credentials to another API host.
+    // Automatic discovery still requires an exact backend match.
+    let response
+    try {
+      response = await fetch(`${next.backend}/projects`, {
+        headers: { accept: 'application/json', 'x-agent-api-key': saved.apiKey, 'x-agent-identifier': saved.identifier },
+        redirect: 'error', signal: AbortSignal.timeout(15000),
+      })
+    } catch { throw new Error('Could not verify credentials at the new backend. Saved settings are unchanged.') }
+    await response.body?.cancel()
+    if (!response.ok) throw new Error(`New backend rejected verification (HTTP ${response.status}). Saved settings are unchanged.`)
+  }
+  const current = readConfig(slug)
+  if (!current || current.apiKey !== saved.apiKey || current.identifier !== saved.identifier || current.backend !== saved.backend) throw new Error('Saved agent identity changed during update; retry the update.')
+  next = { ...current, backend: next.backend, wsUrl: next.wsUrl, mcpUrl: next.mcpUrl, ...(next.setupHost ? { setupHost: next.setupHost } : {}) }
+  saved = current
+
   saveConnectionSettings({ slug, saved, next, registerClaude: true })
   ok(`Updated connection settings for "${slug}".`)
   if (flags.restart) {
@@ -52,6 +73,7 @@ export async function runUpdate({ flags, positional = [] }) {
 export function saveConnectionSettings({ slug, saved, next, registerClaude = false, stateDir = OV_DIR }) {
   const mcpChanged = next.mcpUrl !== saved.mcpUrl
   const wsChanged = next.wsUrl !== saved.wsUrl
+  const backendChanged = next.backend !== saved.backend
   // Prepare every local file before changing anything. Preserve other servers
   // and settings in the agent's scoped MCP configuration.
   let scoped
@@ -73,16 +95,18 @@ export function saveConnectionSettings({ slug, saved, next, registerClaude = fal
   }
   const envPath = join(stateDir, `${slug}.env`)
   let envText
-  if (wsChanged && existsSync(envPath)) {
-    const lines = readFileSync(envPath, 'utf8').split(/\r?\n/)
-    const assignment = `OPENVISIO_AGENT_WS_URL='${next.wsUrl.replace(/'/g, "'\\''")}'`
-    let replaced = false
-    envText = lines.map(line => {
-      if (!/^\s*(?:export\s+)?OPENVISIO_AGENT_WS_URL=/.test(line)) return line
-      replaced = true
-      return assignment
-    }).join('\n')
-    if (!replaced) envText = envText.replace(/\n?$/, '\n') + assignment + '\n'
+  if ((wsChanged || backendChanged) && existsSync(envPath)) {
+    envText = readFileSync(envPath, 'utf8')
+    for (const [key, value] of [...(wsChanged ? [['OPENVISIO_AGENT_WS_URL', next.wsUrl]] : []), ...(backendChanged ? [['OPENVISIO_API_URL', next.backend]] : [])]) {
+      const assignment = `${key}='${value.replace(/'/g, "'\\''")}'`
+      let replaced = false
+      envText = envText.split(/\r?\n/).map(line => {
+        if (!new RegExp(`^\\s*(?:export\\s+)?${key}=`).test(line)) return line
+        replaced = true
+        return assignment
+      }).join('\n')
+      if (!replaced) envText = envText.replace(/\n?$/, '\n') + assignment + '\n'
+    }
   }
 
   // Claude also exposes the team MCP in interactive sessions at user scope.

package/src/watch.mjs

@@ -781,7 +781,9 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, setup
         const runner = replyRunners.acquire(key, { key, canCoordinate: item.kind === 'coord' })
         activeReplyRunners.add(runner)
         item.control.runner = runner
-        try { return await cycleContext.run({ cycleId: item.control.cycleId }, () => executeCycle(item.kind, item.context, item.targetChannels, item.taskRef, item.delivery, runner, item.control, '')) }
+        try { return await cycleContext.run({ cycleId: item.control.cycleId }, () => item.delivery?.watcherOwned
+          ? executeRecoverableCycle(item, runner)
+          : executeCycle(item.kind, item.context, item.targetChannels, item.taskRef, item.delivery, runner, item.control, '')) }
         finally { replyRunners.release(key); activeReplyRunners.delete(runner); item.control.runner = null }
       },
       onError: (error, item) => {
@@ -1710,7 +1712,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, setup
       activity.clear(control.cycleId)
       const delayMs = recoveryDelays[attempt - 1]
       emit('cycle.recovering', { cycleId: control.cycleId, status: 'recovering', attempt, retryInMs: delayMs, reason: 'Runtime connection interrupted; preserving accepted work' })
-      log(`coding runtime connection interrupted; resuming attempt ${attempt + 1} in ${delayMs / 1000}s or on reconnect`)
+      log(`${item.kind === 'full' ? 'coding' : 'reply'} runtime connection interrupted; resuming attempt ${attempt + 1} in ${delayMs / 1000}s or on reconnect`)
       await new Promise((resolve) => {
         const wake = () => { clearTimeout(timer); recoveryWaiters.delete(wake); control.wakeRecovery = null; resolve() }
         // A known event-channel outage can last longer than the retry budget.
@@ -1876,11 +1878,11 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, setup
         return
       }
       if (!cycleSucceeded(result)) {
-        if (kind === 'full' && interruptedRuntimeResult(result) && cycleControl.attempt <= recoveryDelays.length) return { ...result, transportInterrupted: true }
+        if ((kind === 'full' || delivery?.watcherOwned) && interruptedRuntimeResult(result) && cycleControl.attempt <= recoveryDelays.length) return { ...result, transportInterrupted: true }
         const outcome = result?.subtype || 'an unknown runtime error'
         const providerPause = agent === 'opencode' && ['rate_limited', 'authentication_error', 'model_unavailable'].includes(outcome)
           ? { kind, model: result.model || useModel, retryAt: outcome === 'rate_limited' ? Date.now() + 30 * 60_000 : null } : null
-        const providerMessage = providerPause && result.userMessage ? result.userMessage : outcome === 'rate_limited' ? 'The model provider is rate-limiting this request. Choose a model with available quota in Agent Studio, or retry once the limit resets.' : ''
+        const providerMessage = result?.userMessage || (outcome === 'rate_limited' ? 'The model provider is rate-limiting this request. Choose a model with available quota in Agent Studio, or retry once the limit resets.' : '')
         const resumeMessage = providerPause ? (outcome === 'rate_limited'
           ? " I'll retry this ticket after a 30-minute cooldown, or when its model or ticket changes."
           : " I'll resume this ticket when its model or ticket changes; after fixing credentials, update the ticket to retry.") : " I've paused this revision until the ticket changes."
@@ -2067,17 +2069,51 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, setup
     }
   }
 
+  const commentProjectReads = new Map()
+  const resolveCommentProject = (ticketId) => {
+    const key = String(ticketId)
+    if (commentProjectReads.has(key)) return commentProjectReads.get(key)
+    const pending = (async () => {
+      const data = toolData(await callMcpReadWithRetry('list_projects'), 'list_projects')
+      const projects = Array.isArray(data.projects) ? data.projects : []
+      const matches = await mapConcurrent(projects.filter(project => validBackendId(project?.id)), 3, async project => {
+        const tasks = await loadProjectTickets({
+          projectId: Number(project.id),
+          read: async (name, args) => toolData(await callMcpReadWithRetry(name, args), name),
+          listTools: () => mcpClient.listTools(),
+          matches: task => String(task.id) === key,
+        })
+        return tasks.some(task => String(task.id) === key) ? Number(project.id) : null
+      })
+      const ids = [...new Set(matches.filter(id => id != null))]
+      if (ids.length !== 1) throw new Error('Could not resolve one authoritative project for this task comment.')
+      return ids[0]
+    })().finally(() => commentProjectReads.delete(key))
+    commentProjectReads.set(key, pending)
+    return pending
+  }
+
   const handleTaskComment = async (raw) => {
     const event = taskCommentFromEvent(raw)
-    const projectId = event?.projectId
+    let projectId = event?.projectId
     const ticketId = event?.taskId
     const comment = event?.comment
     const commentId = comment && (comment.id ?? comment.comment_id ?? comment.commentId)
     const text = String(comment?.content ?? comment?.body ?? comment?.text ?? comment?.message ?? '').replace(/\s+/g, ' ').trim()
-    if (!validBackendId(projectId) || !validBackendId(ticketId) || !validBackendId(commentId) || !text) {
+    if ((projectId != null && !validBackendId(projectId)) || !validBackendId(ticketId) || !validBackendId(commentId) || !text) {
       log('task:comment missing project/task/comment identity or content — ignored')
       return { status: 'ignored-malformed' }
     }
+    // Backend comment rows carry task_id but not project_id. Some broadcasts
+    // likewise omit the project. Resolve it from authenticated task listings;
+    // never infer it from another event or assume the first project is correct.
+    if (projectId == null) {
+      try { projectId = await resolveCommentProject(ticketId) }
+      catch (error) {
+        log(`task:comment project lookup failed for ticket #${ticketId}: ` + (error?.message || error))
+        return { status: 'retry' }
+      }
+    }
     const sourceKey = `task-comment:${Number(projectId)}:${Number(ticketId)}:${Number(commentId)}`
     if (memory.has(sourceKey, 'received')) {
       log(`task:comment duplicate project=${projectId} ticket=${ticketId} comment=${commentId} — skipped`)
@@ -2114,6 +2150,9 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, setup
         log(`task:comment ticket #${ticketId} is not assigned to this agent — ignored`)
         return { status: 'ignored-unassigned' }
       }
+      // Duplicate deliveries can share the asynchronous project/owner reads.
+      // Recheck immediately before reserving this source and starting work.
+      if (memory.has(sourceKey, 'received')) return { status: 'duplicate' }
       if (peer) {
         const meta = admitPeerTurn(memory.get(loopKey), text, target)
         if (!meta) return { status: 'ignored-peer-loop' }

package/studio/app.mjs

@@ -10,6 +10,29 @@ const timeValue = value => Number.isFinite(Date.parse(value)) ? Date.parse(value
 const agentId = item => text(item?.identifier || item?.id || item?.slug || 'unknown');
 const agentName = item => text(item?.name || item?.slug || item?.identifier || 'Unknown agent');
 
+export const credentialFields = ['name', 'identifier', 'apiKey', 'backend', 'mcpUrl', 'wsUrl', 'setupHost', 'agent'];
+
+export function parseAgentCredentials(value) {
+  let credentials;
+  const source = value.trim().replace(/^```(?:json)?\s*\n([\s\S]*?)\n```$/i, '$1');
+  try { credentials = JSON.parse(source); }
+  catch { throw new Error('Paste a complete JSON credentials object from OpenVisio → Copy credentials.'); }
+  if (!credentials || typeof credentials !== 'object' || Array.isArray(credentials)) throw new Error('Credentials must be a JSON object.');
+  const result = {};
+  for (const key of credentialFields) {
+    const raw = credentials[key];
+    if (raw !== undefined && typeof raw !== 'string') throw new Error(`The ${key} field must be text.`);
+    const field = (raw || '').trim();
+    if (field.length > 4096 || /[\r\n\0]/.test(field)) throw new Error(`Enter a valid ${key}.`);
+    result[key] = field;
+  }
+  const missing = ['name', 'identifier', 'apiKey', 'backend'].filter(key => !result[key]);
+  if (missing.length) throw new Error(`Credentials are missing: ${missing.join(', ')}. Copy the complete object from OpenVisio.`);
+  result.agent = result.agent.toLowerCase() || 'claude';
+  if (!['claude', 'codex', 'opencode', 'gemini', 'qwen'].includes(result.agent)) throw new Error('Choose a supported runtime: Claude Code, Codex, OpenCode, Gemini CLI, or Qwen Code.');
+  return result;
+}
+
 export function normalizeStatus(value, fallback = 'observed') {
   const status = text(value).toLowerCase().replaceAll('-', '_');
   if (['active', 'running', 'started', 'ready', 'in_progress', 'working', 'online', 'preflight'].includes(status)) return 'active';
@@ -400,6 +423,7 @@ function initializeStudio() {
     if (!agent || state.snapshot.demo) return;
     $('model-settings-agent').textContent = `${agentName(agent)} · Models`;
     $('open-model-settings').disabled = !agent.settingsEditable;
+    $('open-connection-update').disabled = !agent.settingsEditable || watcherChanging;
     $('open-agent-removal').disabled = !agent.removable;
     const watcherRunning = agent.status === 'online' || agent.watcherAlive === true;
     $('toggle-watcher').querySelector('span').textContent = watcherRunning ? 'Stop watcher' : 'Start watcher';
@@ -824,30 +848,37 @@ function initializeStudio() {
 
   $('server-address').textContent = location.host;
   let connectingAgent = false;
-  const credentialFields = ['name', 'identifier', 'apiKey', 'backend', 'mcpUrl', 'wsUrl', 'setupHost', 'agent'];
   $('open-agent-connect').addEventListener('click', () => {
     $('agent-connect-error').hidden = true;
     $('agent-connect-dialog').showModal();
   });
   $('close-agent-connect').addEventListener('click', () => { if (!connectingAgent) $('agent-connect-dialog').close(); });
   $('agent-connect-dialog').addEventListener('cancel', event => { if (connectingAgent) event.preventDefault(); });
-  $('agent-connect-dialog').addEventListener('close', () => $('agent-connect-form').reset());
-  $('connect-credentials').addEventListener('input', () => {
-    if (!$('connect-credentials').value.trim()) return;
+  $('agent-connect-dialog').addEventListener('close', () => {
+    $('agent-connect-form').reset();
+    $('connect-import-status').textContent = 'Paste the complete object, then choose Use credentials to review the fields.';
+  });
+  const importCredentials = () => {
+    if (connectingAgent) return false;
     try {
-      const credentials = JSON.parse($('connect-credentials').value);
-      if (!credentials || typeof credentials !== 'object' || Array.isArray(credentials)) throw new Error();
-      for (const key of credentialFields) $('connect-' + key).value = typeof credentials[key] === 'string' ? credentials[key] : key === 'agent' ? 'claude' : '';
+      const credentials = parseAgentCredentials($('connect-credentials').value);
+      for (const key of credentialFields) $('connect-' + key).value = credentials[key];
       $('connect-credentials').value = '';
       $('agent-connect-error').hidden = true;
-    } catch {
-      $('agent-connect-error').textContent = 'Paste the complete credentials from Copy credentials in OpenVisio, or enter the fields below.';
+      $('connect-import-status').textContent = 'Credentials imported. Review the fields, then choose Verify and connect.';
+      return true;
+    } catch (error) {
+      $('agent-connect-error').textContent = error.message;
       $('agent-connect-error').hidden = false;
+      return false;
     }
-  });
+  };
+  $('import-agent-credentials').addEventListener('click', importCredentials);
   $('agent-connect-form').addEventListener('submit', async event => {
     event.preventDefault();
     if (connectingAgent) return;
+    if ($('connect-credentials').value.trim() && !importCredentials()) return;
+    if (!$('agent-connect-form').reportValidity()) return;
     connectingAgent = true;
     $('save-agent-connect').disabled = true;
     $('close-agent-connect').disabled = true;
@@ -966,6 +997,75 @@ function initializeStudio() {
       scheduleRender();
     }
   }
+  let connectionAgent = null, connectionPlan = null, connectionBusy = false;
+  const connectionBusyState = busy => {
+    connectionBusy = busy;
+    for (const id of ['connection-update-host', 'connection-update-object', 'check-connection-update', 'close-connection-update']) $(id).disabled = busy;
+    $('apply-connection-update').disabled = busy || !connectionPlan;
+  };
+  const invalidateConnectionPlan = () => {
+    connectionPlan = null;
+    $('connection-update-preview').hidden = true;
+    $('apply-connection-update').disabled = true;
+    $('connection-update-status').textContent = '';
+    $('connection-update-error').hidden = true;
+  };
+  $('open-connection-update').addEventListener('click', () => {
+    connectionAgent = state.model.agents.find(agent => agentId(agent) === state.selectedAgent);
+    if (!connectionAgent?.settingsEditable) return;
+    $('connection-update-form').reset();
+    invalidateConnectionPlan();
+    $('connection-update-title').textContent = `Update ${agentName(connectionAgent)} connection`;
+    $('connection-update-dialog').showModal();
+    $('connection-update-form').requestSubmit();
+  });
+  $('close-connection-update').addEventListener('click', () => { if (!connectionBusy) $('connection-update-dialog').close(); });
+  $('connection-update-dialog').addEventListener('cancel', event => { if (connectionBusy) event.preventDefault(); });
+  $('connection-update-dialog').addEventListener('close', () => { $('connection-update-form').reset(); invalidateConnectionPlan(); });
+  for (const id of ['connection-update-host', 'connection-update-object']) $(id).addEventListener('input', invalidateConnectionPlan);
+  $('connection-update-form').addEventListener('submit', async event => {
+    event.preventDefault();
+    if (!connectionAgent || connectionBusy) return;
+    invalidateConnectionPlan();
+    connectionBusyState(true);
+    $('connection-update-status').textContent = 'Checking current connection URLs…';
+    try {
+      const input = { action: 'check', setupHost: $('connection-update-host').value.trim() || undefined };
+      const pasted = $('connection-update-object').value.trim();
+      if (pasted) {
+        let parsed;
+        try { parsed = JSON.parse(pasted.replace(/^```(?:json)?\s*\n([\s\S]*?)\n```$/i, '$1')); } catch { throw new Error('Paste a complete JSON connection object.'); }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('Paste a JSON connection object.');
+        input.settings = Object.fromEntries(['backend', 'mcpUrl', 'wsUrl', 'setupHost'].map(key => [key, parsed[key]]));
+        if (input.setupHost) input.settings.setupHost = input.setupHost;
+      }
+      connectionPlan = await settingsFetch(`/api/agents/${encodeURIComponent(connectionAgent.slug)}/connection`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input) });
+      $('connection-update-object').value = '';
+      $('connection-update-preview').textContent = JSON.stringify(connectionPlan.settings, null, 2);
+      $('connection-update-preview').hidden = false;
+      $('connection-update-status').textContent = connectionPlan.backendChanged ? 'The API backend has moved. Review the new URLs before applying. Your saved key will be verified against this backend.' : 'Review the current URLs, then apply and reconnect.';
+    } catch (error) {
+      $('connection-update-status').textContent = '';
+      $('connection-update-error').textContent = error.message;
+      $('connection-update-error').hidden = false;
+    } finally { connectionBusyState(false); }
+  });
+  $('apply-connection-update').addEventListener('click', async () => {
+    if (!connectionPlan || connectionBusy) return;
+    connectionBusyState(true);
+    $('connection-update-error').hidden = true;
+    $('connection-update-status').textContent = 'Verifying and applying connection settings…';
+    try {
+      const result = await settingsFetch(`/api/agents/${encodeURIComponent(connectionAgent.slug)}/connection`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ action: 'apply', ...connectionPlan }) });
+      connectionPlan = null;
+      $('connection-update-status').textContent = result.message;
+      receive(await settingsFetch('/api/snapshot'), true);
+    } catch (error) {
+      $('connection-update-status').textContent = '';
+      $('connection-update-error').textContent = error.message;
+      $('connection-update-error').hidden = false;
+    } finally { connectionBusyState(false); }
+  });
   $('toggle-watcher').addEventListener('click', () => void changeWatcher($('toggle-watcher').dataset.action || 'start'));
   $('restart-watcher').addEventListener('click', () => void changeWatcher('restart'));
   $('pause-button').addEventListener('click', () => {

package/studio/index.html

@@ -65,27 +65,46 @@
         <div id="notice" class="notice" role="status" hidden></div>
         <section id="model-settings-summary" class="model-settings-summary" aria-label="Agent model settings" hidden>
           <div><h2 id="model-settings-agent">Model settings</h2><p id="model-settings-state" role="status"></p></div>
-          <div class="header-actions model-settings-actions-row"><button id="toggle-watcher" class="button studio-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-power"/></svg><span>Start watcher</span></button><button id="restart-watcher" class="button studio-action restart-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-refresh"/></svg><span>Restart watcher</span></button><button id="open-model-settings" class="button studio-action settings-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-sliders"/></svg><span>Model settings</span></button><button id="open-agent-removal" class="button studio-action remove-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-user-minus"/></svg><span>Remove agent</span></button></div>
+          <div class="header-actions model-settings-actions-row"><button id="toggle-watcher" class="button studio-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-power"/></svg><span>Start watcher</span></button><button id="restart-watcher" class="button studio-action restart-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-refresh"/></svg><span>Restart watcher</span></button><button id="open-connection-update" class="button studio-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-refresh"/></svg><span>Update connection</span></button><button id="open-model-settings" class="button studio-action settings-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-sliders"/></svg><span>Model settings</span></button><button id="open-agent-removal" class="button studio-action remove-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-user-minus"/></svg><span>Remove agent</span></button></div>
         </section>
         <dialog id="agent-connect-dialog" aria-labelledby="agent-connect-title">
-          <form id="agent-connect-form" class="model-settings-form" autocomplete="off">
+          <form id="agent-connect-form" class="model-settings-form" autocomplete="off" novalidate>
             <div class="section-heading"><h2 id="agent-connect-title">Connect agent</h2><button id="close-agent-connect" class="button" type="button">Cancel</button></div>
             <p>Copy credentials from OpenVisio after registering your agent, then paste them below. Or enter the fields yourself.</p>
-            <label for="connect-credentials">Paste credentials</label>
-            <textarea id="connect-credentials" rows="3" spellcheck="false" placeholder="Paste the copied credentials here"></textarea>
+            <label for="connect-credentials">Paste generated credentials object</label>
+            <textarea id="connect-credentials" rows="5" spellcheck="false" aria-describedby="connect-import-status" placeholder='Paste the JSON object from OpenVisio → Copy credentials'></textarea>
+            <button id="import-agent-credentials" class="button" type="button">Use credentials</button>
+            <p id="connect-import-status" role="status">Paste the complete object, then choose Use credentials to review the fields.</p>
             <label for="connect-name">Local agent name</label><input id="connect-name" type="text" required maxlength="4096" spellcheck="false">
             <label for="connect-identifier">Agent identifier</label><input id="connect-identifier" type="text" required maxlength="4096" spellcheck="false">
             <label for="connect-apiKey">API key</label><input id="connect-apiKey" type="password" required maxlength="4096" spellcheck="false">
             <label for="connect-backend">Backend URL</label><input id="connect-backend" type="url" required maxlength="4096" spellcheck="false">
-            <label for="connect-mcpUrl">MCP URL</label><input id="connect-mcpUrl" type="url" required maxlength="4096" spellcheck="false">
-            <label for="connect-wsUrl">WebSocket URL</label><input id="connect-wsUrl" type="url" required maxlength="4096" spellcheck="false">
-            <label for="connect-setupHost">OpenVisio app URL (optional)</label><input id="connect-setupHost" type="url" maxlength="4096" placeholder="https://openvisio.app" spellcheck="false">
+            <label for="connect-mcpUrl">MCP URL (optional)</label><input id="connect-mcpUrl" type="url" maxlength="4096" spellcheck="false">
+            <label for="connect-wsUrl">WebSocket URL (optional)</label><input id="connect-wsUrl" type="url" maxlength="4096" spellcheck="false">
+            <p>Missing connection URLs are retrieved from your OpenVisio app when you connect.</p>
+            <label for="connect-setupHost">OpenVisio app URL (optional)</label><input id="connect-setupHost" type="url" maxlength="4096" placeholder="https://openvisio.io" spellcheck="false">
             <label for="connect-agent">Runtime</label><select id="connect-agent"><option value="claude">Claude Code</option><option value="codex">Codex</option><option value="opencode">OpenCode</option><option value="gemini">Gemini CLI</option><option value="qwen">Qwen Code</option></select>
             <p>Install and sign in to your chosen runtime on this computer. After connecting, select the agent and choose Start watcher.</p>
             <p id="agent-connect-error" role="alert" hidden></p>
             <div class="model-settings-actions"><button id="save-agent-connect" class="button primary" type="submit">Verify and connect</button></div>
           </form>
         </dialog>
+        <dialog id="connection-update-dialog" aria-labelledby="connection-update-title">
+          <form id="connection-update-form" class="model-settings-form" autocomplete="off">
+            <div class="section-heading"><h2 id="connection-update-title">Update connection</h2><button id="close-connection-update" class="button" type="button">Close</button></div>
+            <p>Get the latest connection URLs using this agent’s saved credentials. Applying the update restarts the watcher; active work must finish first.</p>
+            <label for="connection-update-host">OpenVisio app URL (optional)</label>
+            <input id="connection-update-host" type="url" placeholder="Use the saved app URL" maxlength="4096">
+            <label for="connection-update-object">Latest connection object (optional)</label>
+            <textarea id="connection-update-object" rows="4" spellcheck="false" placeholder="If automatic discovery is unavailable, paste the connection JSON copied from OpenVisio."></textarea>
+            <p>Your saved API key and agent identity are kept. Only connection URLs are imported.</p>
+            <button id="check-connection-update" class="button" type="submit">Check connection</button>
+            <pre id="connection-update-preview" hidden></pre>
+            <p id="connection-update-status" role="status"></p>
+            <p id="connection-update-error" role="alert" hidden></p>
+            <div class="model-settings-actions"><button id="apply-connection-update" class="button primary" type="button" disabled>Apply and reconnect</button></div>
+          </form>
+        </dialog>
         <dialog id="model-settings-dialog" aria-labelledby="model-settings-title">
           <form id="model-settings-form" class="model-settings-form">
             <div class="section-heading"><h2 id="model-settings-title">Model settings</h2><button id="close-model-settings" class="button" type="button" aria-label="Close model settings">Close</button></div>

package/studio/style.css

@@ -368,8 +368,8 @@
   #toggle-watcher[data-action="stop"] .icon, .remove-action .icon { color: var(--destructive); }
   .restart-action .icon { color: var(--orange); }
   .settings-action .icon { color: var(--purple); }
-  #agent-connect-dialog, #model-settings-dialog, #agent-removal-dialog { width: min(500px, calc(100vw - 32px)); max-height: calc(100dvh - 32px); margin: auto; padding: 24px; overflow-y: auto; border: 1px solid var(--border); border-radius: 24px; color: var(--ink); background: var(--surface, white); box-shadow: 0 24px 80px #0002; }
-  #agent-connect-dialog::backdrop, #model-settings-dialog::backdrop, #agent-removal-dialog::backdrop { background: #0005; }
+  #agent-connect-dialog, #model-settings-dialog, #agent-removal-dialog, #connection-update-dialog { width: min(500px, calc(100vw - 32px)); max-height: calc(100dvh - 32px); margin: auto; padding: 24px; overflow-y: auto; border: 1px solid var(--border); border-radius: 24px; color: var(--ink); background: var(--surface, white); box-shadow: 0 24px 80px #0002; }
+  #agent-connect-dialog::backdrop, #model-settings-dialog::backdrop, #agent-removal-dialog::backdrop, #connection-update-dialog::backdrop { background: #0005; }
   .model-settings-form { display: grid; gap: 12px; }
   .model-settings-form h2 { font-size: 17px; font-weight: 500; }
   .model-settings-form p { margin: 0; font-size: 12px; line-height: 1.6; color: var(--muted); }
@@ -377,7 +377,7 @@
   .model-settings-form label span { font-size: 12px; color: var(--muted); }
   .model-settings-form input, .model-settings-form textarea, .model-settings-form select { width: 100%; min-width: 0; padding: 11px 14px; border: 1px solid var(--border); border-radius: 18px; background: transparent; color: var(--ink); font-size: 13px; }
   .model-settings-actions { display: flex; flex-wrap: wrap; justify-content: space-between; gap: 12px; margin-top: 8px; }
-  #agent-connect-error, #model-settings-error, #agent-removal-error { color: #9f3030; }
+  #agent-connect-error, #model-settings-error, #agent-removal-error, #connection-update-error { color: #9f3030; }
   @media (max-width: 640px) {
     .page-header { flex-direction: column; }
     .header-actions { flex-direction: row; flex-wrap: wrap; align-items: center; padding: 0; gap: 8px; }
@@ -406,3 +406,5 @@
   }
   @media (prefers-reduced-motion: reduce) { *, *::before, *::after { transition-duration: 0s !important; animation-duration: 0s !important; scroll-behavior: auto !important; } }
 }
+
+  #connection-update-preview { white-space: pre-wrap; overflow-wrap: anywhere; min-width: 0; font-size: 12px; line-height: 1.6; }