openvisio-agent 0.25.12 → 0.25.14

package/src/watch.mjs

@@ -18,7 +18,7 @@ import { createContextService } from './context-service.mjs'
 import { contextToolGuide } from './context-tools.mjs'
 import { loadProjectTickets, needsWorkContinuation } from './work-recovery.mjs'
 import { toolWithoutCredentialInputs } from './codex-mcp-proxy.mjs'
-import { compactAgentMessage } from './tool-policy.mjs'
+import { compactAgentMessage, ITEM_REFERENCE_GUIDANCE } from './tool-policy.mjs'
 import { repositoryHasPrPushAuthorization, configurePrPublishing } from './pr-push.mjs'
 import { createMcpHttpClient } from './mcp-http.mjs'
 import { createCycleQueue } from './cycle-queue.mjs'
@@ -30,6 +30,8 @@ import { releaseAuthorizedPause } from './authorization-resume.mjs'
 import { dedicatedChannel, repliesAfterSource } from './channel-routing.mjs'
 import { createTaskTypeLookup, loadProjectTaskTypes } from './task-types.mjs'
 import { createThreadContextResolver } from './thread-context.mjs'
+import { compileConversationContext, createConversationReader, conversationAuthor, checkedConversationResult } from './conversation-context.mjs'
+import { admitPeerTurn } from './peer-turns.mjs'
 import { assignmentRequest, assignmentStatusOnly, routeAssignments } from './assignment-routing.mjs'
 import { modelProcessOptions, stopModelProcess } from './process-lifecycle.mjs'
 import { createMastraAcpRunner } from './mastra-harness.mjs'
@@ -38,6 +40,7 @@ import { createAgentJournal } from './agent-journal.mjs'
 import { readModelSettings } from './model-settings.mjs'
 import { startStudioInBackground } from './studio-cli.mjs'
 import { toolData } from './team-data.mjs'
+import { REPORT_ROUTING_PROMPT, reportChannelSelection } from './report-routing.mjs'
 import { runtimeProvider, supportedRuntimeList } from './runtime-providers.mjs'
 
 function runtimeJournal(options, supplied) {
@@ -80,6 +83,7 @@ function findTicketWorktree(workspaceRoot, ticketId) {
 // answering a question meant for a DIFFERENT agent, and claiming something works
 // then walking it back.
 const REPLY_DISCIPLINE = [
+  ITEM_REFERENCE_GUIDANCE,
   'REPLY DISCIPLINE — read the recent messages FIRST, then decide whether to speak at all:',
   '  • FIRST-PERSON VOICE. Speak as yourself: use “I”, “I\'m”, and “my”. Never refer to yourself by your agent name or in the third person, and never restate your own name in introductions, acknowledgements, progress, blockers, or results. The app already shows who sent the message. Sound like a warm, accountable teammate, not a status bot.',
   '  • IS IT FOR YOU? Act ONLY on messages addressed to YOU — an @mention of your exact name, a direct question to you, or a reply to something YOU said or did. If a DIFFERENT agent or person was @mentioned or asked to do something, STAY OUT: do not answer for them and do not pick up their task. When it is not yours, posting nothing is the correct move.',
@@ -89,9 +93,9 @@ const REPLY_DISCIPLINE = [
   '  • USE RECALL, NEVER INVENT IT. Before answering a context-dependent question, search the visible thread and use any available history, search, docs, or recall tools. Reuse verified context instead of asking the user to repeat it. If no record exists, say plainly "I don\'t have a record of that". Never fabricate past events, conversations, results, links, PR numbers, deploy URLs, or figures.',
   '  • LOOK UP ASSIGNED WORK. If someone says they assigned you a task, asks which task is yours, or asks for its status, check the live board yourself with list_projects + list_tasks and then get_ticket as needed. Use list_agents only if assignment data requires a numeric identity lookup. Match assignments to your authenticated agent identity. Do not ask the teammate for a project slug, ticket slug, or numeric id before trying those MCP tools; ask only if the live lookup fails or returns genuinely ambiguous matches.',
   '  • ASSIGNEE IDS ARE HUMAN IDS. On task mutations, assignee_id means a human user/member. agent_id means a registered agent. Never put an agent id in assignee_id, never put a human id in agent_id, and never send both. To assign work to yourself or another agent, resolve the registered agent and use agent_id.',
-  '  • TICKET SLUGS, NEVER DATABASE IDS. In every human-facing channel message, ticket comment, PR description, summary, blocker, and result, reference a ticket by the exact project-scoped slug returned by get_ticket/list_tasks (for example, `OVS-57`). Numeric project_id and ticket_id values are internal MCP arguments only: never write `#57`, `ticket 57`, or expose a database id to teammates. If the backend omits the slug, use the ticket title or say “the ticket”; do not invent a slug.',
+  '  • TICKET SLUGS, NEVER DATABASE IDS. In every human-facing channel message, ticket comment, PR description, summary, blocker, and result, reference a ticket by the exact project-scoped slug returned by get_ticket/list_tasks (for example, `OVS-57`). Numeric project_id and ticket_id values belong only in MCP arguments or verified link destinations: never write `#57`, `ticket 57`, or expose a database id to teammates. If the backend omits the slug, use the ticket title or say “the ticket”; do not invent a slug.',
   '  • CLOSE CONCERNS. Never leave a concern, direct question, correction, or blocker addressed to you without a clear response. Acknowledge the concern, act if you can, then report the verified result. If blocked, name the blocker and the exact next action or owner in one message.',
-  '  • HONOR CHANNEL DESTINATIONS. Reply to an existing request in its original thread. When a teammate explicitly asks you to send, post, announce, or share something in another channel, resolve that exact destination from live list_channels and post there. Use your dedicated agent channel for fresh top-level results, blockers, and introductions only when no other destination was requested. Never invent a channel id or silently substitute a different channel.',
+  '  • HONOR CHANNEL DESTINATIONS. Reply to an existing request in its original thread. When a teammate explicitly asks you to send, post, announce, or share something in another channel, resolve that exact destination from live list_channels and post there. For a task result without a source thread or explicit destination, choose the existing channel that best fits the project, subject, and audience; a dedicated agent channel is not required. Never invent a channel id or silently substitute a different explicitly requested channel.',
   '  • KEEP MESSAGES COMPACT. Lead with the answer, result, decision, or blocker. Default to 1-4 short sentences or at most 6 brief bullets, normally under 600 characters and never over 1,200. Do not restate the prompt, narrate routine tool use, dump raw logs, or repeat context already visible in the thread. Task descriptions may use up to 2,400 characters when acceptance details require it.',
   '  • END AGENT-TO-AGENT TURNS. Answer one concrete peer-agent request once, without a reciprocal question, invitation, thank-you exchange, or status echo. Then wait for a human or a genuinely new human-directed request. Do not keep a conversation alive merely because another agent replied.',
   '  • WRITE PLAINLY. Prefer short sentences, commas, periods, and colons. Avoid em dashes except when reproducing quoted text.',
@@ -135,7 +139,7 @@ const CODE_CHARTER = [
   '',
   'WORK ETHIC — how a reliable teammate behaves (this is the difference between useful and ignored):',
   '  1. CLOSE THE LOOP in THIS cycle. Never say "I\'ll do X" and stop. If you commit to something, do it NOW — the human must never have to remind you to circle back. Sending an intent or progress message is not a stop condition: continue using tools and send the verified result or blocker afterward.',
-  '  2. FINISH, then REPORT. Update the ticket when the actual work calls for a state change. Reply in a supplied human source thread when one exists. For backlog-assigned work, do not call post_message yourself: the watcher publishes your final response in the dedicated agent channel.',
+  '  2. FINISH, then REPORT. Update the ticket when the actual work calls for a state change. Reply in a supplied human source thread when one exists. For backlog-assigned work, do not call post_message yourself: the watcher asks you to choose a suitable existing channel and publishes your final response there.',
   '  3. Be honest and specific. Never invent progress. If you are genuinely blocked (missing repo, unclear spec, a failing tool), say exactly what you need in one message — that IS closing the loop.',
   '  4. One final reply per request; answer several nudges together. A single concrete progress update is allowed during longer work, but it must be followed by the final result or blocker in the same cycle.',
   '  5. RECOVER DEAD COMMAND SESSIONS. If write_stdin reports “Unknown process id”, that command session has already exited. Never poll the same process id again. Start a fresh exec_command when more work is required, then continue the task and verify the final state.',
@@ -155,7 +159,7 @@ const CODE_FULL = [
   'Use available tool discovery, resources, history, search, skills, and planning tools when useful. Prefer the repository knowledge graph when available. Recover from optional tool failures using alternatives; report only a limitation that actually prevents the requested outcome.',
   'A usable local clone is your primary code surface. Preserve unrelated work and use an isolated worktree when needed. Remote codebase tools are a fallback only when the repository cannot be obtained locally. For code changes, verify the result and use the authorized branch/PR flow when the request calls for it.',
   'You own ticket state: use update_ticket when its state should change, including review, completion, or a real blocker. Ending your turn does not mark the ticket done. Your native final response ends this cycle; it can report a result, ask a necessary question, or explain a blocker. Do not describe unperformed work as complete.',
-  'Follow the supplied source delivery rule. For backlog-only tickets, return your final response; the watcher delivers it once to your dedicated channel. Do not call post_message for that same result.',
+  'Follow the supplied source delivery rule. For backlog-only tickets, return your final response; the watcher asks you to select the best-fitting existing channel and delivers the saved report once. Do not call post_message for that same result.',
 ].join('\n')
 
 const CODE_FAST = [
@@ -627,7 +631,6 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   const replyStatusTargets = new Set()
   const activity = dependencies.activityReporter || createActivityReporter({
     backend, apiKey, identifier, log,
-    sendFrame: (frame) => handle?.send?.(frame) === true,
   })
   const sendStatus = (channelId, state) => {
     const id = cycleContext.getStore()?.cycleId
@@ -1009,6 +1012,21 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     }).finally(() => { mcpToolDiscoveryPromise = null })
     return mcpToolDiscoveryPromise
   }
+  const conversationReader = createConversationReader({ load: async (scope) => {
+    const names = await discoverMcpTools()
+    const ticket = scope.ticketId != null
+    const tool = ticket ? 'list_task_comment_thread' : 'list_message_thread'
+    if (!names.has(tool)) throw new Error('Conversation thread tool not advertised')
+    const args = ticket ? { project_id: scope.projectId, ticket_id: scope.ticketId, comment_id: scope.threadId }
+      : { channel_id: scope.channelId, message_id: scope.threadId }
+    const [thread, surroundings] = await Promise.all([
+      callMcpTool(tool, args).then(checkedConversationResult),
+      !ticket && names.has('list_channel_messages')
+        ? callMcpTool('list_channel_messages', { channel_id: scope.channelId, limit: 12, before_id: scope.threadId }).then(checkedConversationResult).catch(() => null)
+        : null,
+    ])
+    return { thread, surroundings }
+  } })
   const callOptionalTicketComment = async ({ projectId, ticketId, content, parentId }) => {
     let names
     try { names = await discoverMcpTools() }
@@ -1166,7 +1184,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     save: saveOwnThread,
     cancelled: (cid, root) => memory.has(threadControlKey(cid, root), 'cancelled'),
     identity: () => ({ id: selfAgentId, identifier, slug, name: slug }),
-    load: async (cid, root) => toolData(await callMcpTool('list_message_thread', { channel_id: Number(cid), message_id: Number(root) })),
+    load: async (cid, root) => (await conversationReader.read({ channelId: Number(cid), threadId: Number(root) })).thread,
   })
   const peerTurnKey = (surface, ...parts) => `peer-turn:${surface}:${parts.map((value) => String(value ?? '?')).join(':')}`
   const ownTaskCommentKey = (projectId, ticketId, content) => {
@@ -1174,7 +1192,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     return `own-task-comment:${projectId}:${ticketId}:${normalized.length}:${normalized.slice(0, 120)}:${normalized.slice(-120)}`
   }
   const rememberPeerReply = (key, refs = {}) => {
-    if (key) memory.remember({ key, kind: 'peer-turn', state: 'replied', summary: 'Replied once to a peer agent; waiting for a human turn.', refs })
+    if (key) memory.remember({ key, kind: 'peer-turn', state: 'replied', summary: 'Replied to a peer; bounded concrete follow-ups remain available.', refs, meta: memory.get(key)?.meta })
   }
   const postMessageOnce = async ({ key, channelId, parentId, projectId, content, skipIfAnyAgentReply = false, sourceKey = '', sourceMessageId, allowCancelled = false, peerLoopKey = '', isCancelled = () => false }) => {
     if (stopping) throw new Error('Watcher is stopping')
@@ -1194,6 +1212,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     const controlKey = threadControlKey(channelId, parentId)
     const suppressCancelled = () => {
       if (isCancelled()) return { posted: false, reason: 'cycle-cancelled' }
+      if (sourceMessageId != null && memory.has(`deleted-message:${channelId}:${sourceMessageId}`, 'deleted')) return { posted: false, reason: 'source-deleted' }
       if (memory.has(deliveryKey, 'suppressed')) return { posted: false, reason: 'source-cancelled' }
       if (allowCancelled || !controlKey || !memory.has(controlKey, 'cancelled')) return null
       pendingReplyDeliveries.delete(deliveryKey)
@@ -1212,7 +1231,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     }
     const run = (async () => {
       if (parentId != null) {
-        const live = toolData(await callMcpTool('list_message_thread', { channel_id: Number(channelId), message_id: Number(parentId) }))
+        const live = checkedConversationResult(await callMcpTool('list_message_thread', { channel_id: Number(channelId), message_id: Number(parentId) }))
         const plans = skipIfAnyAgentReply ? memory.recall({ channelId: Number(channelId), threadId: Number(parentId) }, 1000).filter(node => node.kind === 'work-plan' && node.meta?.sourceKey === sourceKey) : []
         const rendered = repliesAfterSource(renderedAgentMessages(live, { id: selfAgentId, identifier, slug, name: slug }), sourceMessageId).filter(row => !plans.some(plan => normalizeRenderedMessageText(plan.summary) === normalizeRenderedMessageText(row.content)))
         const duplicate = rendered.some((row) => normalizeRenderedMessageText(row.content) === normalizeRenderedMessageText(message))
@@ -1364,7 +1383,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     if (!Number.isFinite(projectId) || !Number.isFinite(ticketId)) return false
     const taskKey = `${projectId}:${ticketId}`
     if (String(result.outputText || '').trim()) {
-      pendingAgentResults.set(taskKey, { outputText: result.outputText, didChannelMessage: !!result.didChannelMessage })
+      pendingAgentResults.set(taskKey, { outputText: result.outputText, didResultMessage: !!result.didResultMessage })
       pendingCompletionReports.add(taskKey)
       trimMap(pendingAgentResults); trimSeen(pendingCompletionReports); persistReplay()
     }
@@ -1397,9 +1416,9 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
       try {
         const comment = await callOptionalTicketComment({ projectId, ticketId, content: report.content })
         if (comment.called) log('posted verified ticket comment for #' + ticketId)
-        else log('no ticket comment tool is exposed; completing ticket #' + ticketId + ' through its verified state and dedicated-channel report')
+        else log('no ticket comment tool is exposed; completing ticket #' + ticketId + ' through its verified state and channel report')
       } catch (e) {
-        log('optional ticket comment failed for #' + ticketId + ': ' + (e?.message || e) + '; continuing with the verified dedicated-channel report')
+        log('optional ticket comment failed for #' + ticketId + ': ' + (e?.message || e) + '; continuing with the verified channel report')
       }
       reportedTaskComments.add(report.key); trimSeen(reportedTaskComments); persistReplay()
     }
@@ -1408,19 +1427,52 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
       persistReplay()
       return true
     }
-    // A model may already have replied when the task originated in a real source
-    // thread. Mark that verified completion as delivered instead of posting a
-    // second top-level copy.
-    if (result.didChannelMessage) {
+    // Only a result posted after the work counts as completion delivery. An
+    // earlier acknowledgement/progress message must not suppress the final.
+    if (result.didResultMessage) {
       reportedCompletions.add(report.key); trimSeen(reportedCompletions)
       pendingCompletionReports.delete(taskKey); pendingAgentResults.delete(taskKey); persistReplay()
       log('completion for ticket #' + ticketId + ' was already posted by the work cycle')
       return true
     }
-    const channelId = await projectStatusChannel(projectId)
-    if (channelId == null || !Number.isFinite(channelId)) return false
+    // The agent chooses the audience from live channels, independently of the
+    // completed coding turn. Save its choice so retries never repeat the work.
+    const channelData = toolData(await callMcpTool('list_channels'), 'list_channels')
+    const channels = (Array.isArray(channelData.channels) ? channelData.channels : []).filter(channel => validBackendId(channel?.id))
+    if (!channels.length) return false
+    let channel = channels.find(row => Number(row.id) === result.channelId)
+    if (!channel) {
+      if (isCancelled() || stopping) return false
+      const routingRunner = makeRunner({ ...runnerOptions, workdir: '', workspaceAvailable: false,
+        systemPrompt: identityContext + '\n\n' + credNote + '\n\n' + REPORT_ROUTING_PROMPT,
+        cfgKey: identifier + '-report-' + slugify(taskKey),
+      })
+      activeReplyRunners.add(routingRunner)
+      try {
+        const names = await discoverMcpTools()
+        const selection = await routingRunner.runCycle(REPORT_ROUTING_PROMPT + '\n\n' + JSON.stringify({
+          task: { projectId, ticketId, title: ticket.title, description: ticket.description },
+          report: report.content,
+          channels: channels.map(row => ({ id: Number(row.id), name: row.name, description: row.description, projectId: row.project_id, agentId: row.agent_id })),
+        }), liteModel, {
+          purpose: 'report-routing', cycleId: `${journal.runId}:report:${report.key}`,
+          contextRefs: { projectId, ticketId },
+          disabledMcpTools: [...names].filter(name => !['list_channels', 'get_channel', 'list_projects', 'get_project', 'get_ticket'].includes(name)),
+        })
+        if (!cycleSucceeded(selection) || isCancelled() || stopping) return false
+        channel = reportChannelSelection(selection.outputText, channels)
+        if (!channel) { log('Agent channel selection was not a live channel; saved report remains pending'); return false }
+        result.channelId = Number(channel.id)
+        persistReplay()
+        emit('delivery.routed', { status: 'selected', channelId: result.channelId, ticket: { projectId, ticketId } })
+      } finally {
+        activeReplyRunners.delete(routingRunner)
+        await routingRunner.close?.()
+      }
+    }
+    const channelId = Number(channel.id)
     if (isCancelled()) return false
-    await postMessageOnce({ key: `completion:${report.key}`, projectId, channelId, content: report.content, sourceKey: memoryKey })
+    await postMessageOnce({ key: `completion:${report.key}`, channelId, content: report.content, sourceKey: memoryKey })
     reportedCompletions.add(report.key); trimSeen(reportedCompletions)
     pendingCompletionReports.delete(taskKey); pendingAgentResults.delete(taskKey); persistReplay()
     memory.remember({ key: memoryKey, kind: 'ticket', state: 'reported', summary: report.content, refs: { projectId, ticketId, channelId }, meta: { reportKey: report.key, prUrl: report.prUrl } })
@@ -1532,8 +1584,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
             if (taskIsCompleted(task, doneIds) || taskIsAwaitingReview(task, reviewIds)) {
               memory.remember({ key: `ticket:${project.id}:${task.id}`, kind: 'ticket', state: 'handoff', summary: task.title, refs: { projectId: project.id, ticketId: task.id } })
               if (pendingCompletionReports.has(taskKey)) {
-                const activityChannel = await projectStatusChannel(project.id)
-                try { await announceTaskCompletion({ projectId: project.id, ticketId: task.id, channelId: activityChannel }) }
+                try { await announceTaskCompletion({ projectId: project.id, ticketId: task.id }) }
                 catch (e) { log('completion report retry failed for ticket #' + task.id + ': ' + (e?.message || e)) }
               }
               if (blockedTasks.delete(taskKey)) { blockedTaskRepos.delete(taskKey); persistReplay() }
@@ -1678,6 +1729,12 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
       : activeTaskRef ? { projectId: activeTaskRef.projectId, ticketId: activeTaskRef.ticketId } : {}
     let recalled = ''
     runnerOptions.contextRefs = memoryRefs
+    if (delivery?.sourceMessage) {
+      let snapshot, unavailable = !!delivery.contextUnavailable
+      try { if (!unavailable) snapshot = await conversationReader.read(memoryRefs) }
+      catch (error) { unavailable = true; log('Compiled conversation history unavailable: ' + (error?.message || error)) }
+      ctx.push(compileConversationContext({ ...snapshot, source: delivery.sourceMessage, scope: memoryRefs, unavailable }))
+    }
     try { recalled = await memory.context(memoryRefs) }
     catch (error) { log('Optional history unavailable; agent can retrieve context with its tools: ' + (error?.message || error)) }
     const capabilityContext = kind !== 'full' && canCode
@@ -1797,7 +1854,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
         finishedTaskVersions.set(`${activeTaskRef.projectId}:${activeTaskRef.ticketId}`, verifiedTaskRevision)
         trimMap(finishedTaskVersions); persistReplay()
       }
-      if (activeTaskRef) {
+      if (activeTaskRef && !delivery?.watcherOwned) {
         try {
           const delivered = await announceTaskCompletion(activeTaskRef, completionResult, () => cycleControl.cancelled)
           if (!delivered) {
@@ -1827,6 +1884,8 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   // Distill an event's WS payload into a directive the model can act on without
   // any extra lookup.
   const senderName = (m) => {
+    const attributed = conversationAuthor(m || {})
+    if (attributed.kind === 'agent' && attributed.name !== 'Unknown') return attributed.name
     const s = m && (m.taskSender || m.task_sender || m.sender || m.user || m.author || m.member || m.taskSenderAgent || m.task_sender_agent || m.senderAgent || m.sender_agent || m.agent)
     if (!s) return ''
     return (`${s.first_name || s.firstName || ''} ${s.last_name || s.lastName || ''}`.trim() || s.name || s.display_name || s.identifier || s.email || '')
@@ -1906,8 +1965,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
       if (taskIsCompleted(ticket, typeSets.done) || taskIsAwaitingReview(ticket, typeSets.review)) {
         memory.remember({ key: `ticket:${projectId}:${ticketId}`, kind: 'ticket', state: 'handoff', summary: ticket.title, refs: { projectId, ticketId } })
         if (pendingCompletionReports.has(key)) {
-          const activityChannel = await projectStatusChannel(projectId)
-          try { await announceTaskCompletion({ projectId, ticketId, channelId: activityChannel }) }
+          try { await announceTaskCompletion({ projectId, ticketId }) }
           catch (e) { log('completion report failed for ticket #' + ticketId + ': ' + (e?.message || e) + '; retained for reconnect retry') }
         }
         blockedTasks.delete(key); blockedTaskRepos.delete(key); failedTaskVersions.delete(key); failedOpenCodeProviders.delete(key); persistReplay(); seenTasks.delete(key)
@@ -1936,7 +1994,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
       if (activityChannel != null) sendStatus(activityChannel, 'thinking')
       const humanTicketRef = ticketSlug ? `ticket ${ticketSlug}` : `the ticket “${title}”`
       const workspaceDirective = preparedWorktree ? ` A prepared local git worktree for this ticket exists at ${JSON.stringify(preparedWorktree)}. Start repository inspection and edits there. Do not call list_codebases, codebase_tree, or get_codebase while this local worktree is available.` : ''
-      void drain(cycleKind, `Authoritative get_ticket verification confirms ${humanTicketRef} is open and assigned to YOU. Internal tool identity: project_id ${projectId}, ticket_id ${ticketId}. For every get_ticket call pass exactly { project_id: ${projectId}, ticket_id: ${ticketId} }; For list_task_types, follow its advertised schema: resolve the ticket’s board_id from the ticket or list_boards and include it when required. Never guess a board id. Numeric ids are MCP arguments only and must never appear in human-facing text; use ${ticketSlug || 'the ticket title'} instead. Ticket details: ${JSON.stringify({ slug: ticketSlug, title, description: ticket.description, priority: ticket.priority, typeId: ticket.type_id ?? ticket.typeId })}.${workspaceDirective} This assignment has no source thread: do not call post_message yourself. Choose the tools, context, validation, and ticket state appropriate to this request. Return your final response when you decide this turn is finished; the watcher will publish it once in the dedicated agent channel without changing ticket status.`, activityChannel == null ? [] : [activityChannel], { projectId, ticketId, channelId: activityChannel })
+      void drain(cycleKind, `Authoritative get_ticket verification confirms ${humanTicketRef} is open and assigned to YOU. Internal tool identity: project_id ${projectId}, ticket_id ${ticketId}. For every get_ticket call pass exactly { project_id: ${projectId}, ticket_id: ${ticketId} }; For list_task_types, follow its advertised schema: resolve the ticket’s board_id from the ticket or list_boards and include it when required. Never guess a board id. Numeric ids are MCP arguments only and must never appear in human-facing text; use ${ticketSlug || 'the ticket title'} instead. Ticket details: ${JSON.stringify({ slug: ticketSlug, title, description: ticket.description, priority: ticket.priority, typeId: ticket.type_id ?? ticket.typeId })}.${workspaceDirective} This assignment has no source thread: do not call post_message yourself. Choose the tools, context, validation, and ticket state appropriate to this request. Return your final response when you decide this turn is finished; the watcher will ask you to select the best-fitting existing channel and publish it there without changing ticket status. A dedicated agent channel is not required.`, activityChannel == null ? [] : [activityChannel], { projectId, ticketId, channelId: activityChannel })
     } catch (e) {
       log(kind + ' ticket verification failed for #' + ticketId + ': ' + (e?.message || e))
     }
@@ -1968,11 +2026,6 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     if (messageSenderIsSelf(comment, { id: selfAgentId, identifier, slug, name })) return { status: 'ignored-self' }
     const peer = messageSenderIsAgent(comment)
     const loopKey = peerTurnKey('task-comment', projectId, ticketId, rootCommentId)
-    if (peer && memory.has(loopKey, 'replied')) {
-      log(`task:comment project=${projectId} ticket=${ticketId} ignored after one peer-agent reply; waiting for a human turn`)
-      return { status: 'ignored-peer-loop' }
-    }
-    if (!peer) memory.remember({ key: loopKey, kind: 'peer-turn', state: 'human', summary: text, refs: { projectId: Number(projectId), ticketId: Number(ticketId), threadId: Number(rootCommentId) } })
     const target = classifyConversationTarget(comment, [...selfAliases], { threadOwned: true })
     if (target.action !== 'handle') {
       log('task:comment ignored before model start (' + target.reason + ')')
@@ -1994,6 +2047,12 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
         log(`task:comment ticket #${ticketId} is not assigned to this agent — ignored`)
         return { status: 'ignored-unassigned' }
       }
+      if (peer) {
+        const meta = admitPeerTurn(memory.get(loopKey), text, target)
+        if (!meta) return { status: 'ignored-peer-loop' }
+        memory.remember({ key: loopKey, kind: 'peer-turn', state: 'reserved', meta })
+      } else memory.remember({ key: loopKey, kind: 'peer-turn', state: 'human' })
+      conversationReader.invalidate({ projectId: Number(projectId), ticketId: Number(ticketId), threadId: Number(rootCommentId) })
       const who = senderName(comment)
       const ticketSlug = ticketDisplaySlug(ticket)
       memory.remember({ key: sourceKey, kind: 'task-comment', state: 'received', summary: text, refs: { projectId: Number(projectId), ticketId: Number(ticketId), messageId: Number(commentId), threadId: Number(rootCommentId) } })
@@ -2006,6 +2065,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
         sourceKey,
         watcherOwned: true,
         peerLoopKey: peer ? loopKey : '',
+        sourceMessage: { ...comment, id: Number(commentId) },
       }
       const label = ticketSlug || String(ticket.title || 'the assigned ticket')
       const context = `The watcher received a new comment on your assigned ticket ${JSON.stringify(label)} from ${JSON.stringify(who || (peer ? 'another agent' : 'a teammate'))}: ${JSON.stringify(text)}. Authoritative ticket details: ${JSON.stringify({ slug: ticketSlug, title: ticket.title, description: ticket.description, priority: ticket.priority, status: ticket.type?.name ?? ticket.task_type?.name ?? ticket.status ?? ticket.state })}. Answer the comment directly in the context of this ticket. Do not call post_message or any task-comment tool; return only the final reply and the watcher will post it once in the source comment thread.${peer ? ' This was authored by another team agent. Address its concrete question or request without replacing it with ticket inventory or adding an open-ended reciprocal question.' : ''}`
@@ -2026,7 +2086,12 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     const messageCandidate = [outer.message, data.message, payload.message].find((item) => item && typeof item === 'object' && !Array.isArray(item))
     const directId = source.message_id ?? source.messageId ?? source.id
     const directContent = source.content ?? source.body ?? source.text ?? (typeof source.message === 'string' ? source.message : null)
-    const message = messageCandidate || (directId != null && directContent != null ? { ...source, content: directContent } : {})
+    let message = messageCandidate || (directId != null && directContent != null ? { ...source, content: directContent } : {})
+    const messageId = message.message_id ?? message.messageId ?? message.id
+    // The documented mention envelope may provide the root outside message.
+    // Explicit inner parent fields always win, including malformed ones.
+    if (!['parent_id', 'parentId', 'thread_id', 'threadId', 'reply_to', 'replyTo'].some((key) => message[key] != null)
+      && validBackendId(source.thread_root_id) && String(source.thread_root_id) !== String(messageId)) message = { ...message, parent_id: Number(source.thread_root_id) }
     const channelId = source.channel_id ?? source.channelId ?? source.channel?.id ?? message.channel_id ?? message.channelId ?? message.channel?.id
     return { ...source, channel_id: channelId, message }
   }
@@ -2034,6 +2099,31 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   const mentionIntake = new Map()
   function onEvent(k, d) {
     if (stopping) return
+    if (['channel:message:updated', 'channel:message:deleted', 'channel:message:reaction'].includes(k)) {
+      const event = conversationEventData(d)
+      if (validBackendId(event.channel_id)) {
+        conversationReader.clearChannel(Number(event.channel_id))
+        const mid = event.message?.id ?? event.message_id
+        if (k === 'channel:message:deleted' && validBackendId(mid)) {
+          memory.remember({ key: `deleted-message:${Number(event.channel_id)}:${Number(mid)}`, kind: 'message-deletion', state: 'deleted' })
+          contextService.forget(`message:${Number(event.channel_id)}:${Number(mid)}`)
+          contextService.forgetThread?.(Number(event.channel_id), Number(mid))
+          cancelThread(Number(event.channel_id), Number(mid), 'Source message deleted')
+          // A reply can itself be the accepted request. Cancel just its work,
+          // without standing down unrelated requests in the parent thread.
+          const fromDeletedSource = (delivery) => Number(delivery?.channelId) === Number(event.channel_id) && Number(delivery?.sourceMessageId) === Number(mid)
+          for (const [key, delivery] of pendingReplyDeliveries) if (fromDeletedSource(delivery)) pendingReplyDeliveries.delete(key)
+          for (const queue of Object.values(queues)) queue.cancel((item) => fromDeletedSource(item.delivery), (item) => {
+            item.control.cancelled = true; item.control.wakeRecovery?.()
+            void item.control.runner?.cancelCurrent?.('source-deleted')
+          })
+          persistReplay()
+        } else if (k === 'channel:message:updated') {
+          try { contextService.observe({ name: 'list_message_thread', args: { channel_id: Number(event.channel_id) }, result: event.message }) } catch { /* live read remains authoritative */ }
+        }
+      }
+      return
+    }
     if (k === 'task:comment') return trackOperation(handleTaskComment(d))
     const conversationEvent = k === 'agent:mention' || k === 'agent:message' || k === 'channel:message'
     if (!conversationEvent) return trackOperation(routeEvent(k, d))
@@ -2044,6 +2134,8 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     const messageId = message.message_id ?? message.messageId ?? message.id
     const malformedParent = parent == null && [message.parent_id, message.parentId, message.thread_id, message.threadId, message.reply_to, message.replyTo].some((value) => value != null)
     if (malformedParent || !validBackendId(cid) || !validBackendId(messageId) || (parent != null && !validBackendId(parent))) { log('mention missing valid channel/message identity; ignored'); return }
+    if (memory.has(`deleted-message:${Number(cid)}:${Number(messageId)}`, 'deleted') || parent != null && memory.has(`deleted-message:${Number(cid)}:${Number(parent)}`, 'deleted')) return
+    conversationReader.clearChannel(Number(cid))
     const key = `${cid}:${parent ?? message.message_id ?? message.messageId ?? message.id}`
     // Keep redirects ordered while a legacy root is being verified. Other
     // conversations can resolve and run independently.
@@ -2063,9 +2155,10 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
       // Organization fanout includes our own posts. Ignore stable self identity
       // before recipient checks, replay guards or thread cancellation run.
       if (messageSenderIsSelf(message, { id: selfAgentId, identifier })) return { status: 'ignored-self' }
-      const preliminary = classifyConversationTarget(message, [...selfAliases])
+      const preliminary = classifyConversationTarget(message, [...selfAliases], { threadOwned: parent != null && memory.has(threadControlKey(cid, parent), 'active') })
       const irrelevant = preliminary.action === 'ignore' && preliminary.reason !== 'unaddressed-thread-activity'
       let rootContent = ''
+      let contextUnavailable = false
       if (parent != null && !irrelevant && preliminary.action !== 'stand_down') {
         const optional = preliminary.explicitSelf || memory.has(threadControlKey(cid, parent), 'active')
         let contextTimer
@@ -2076,20 +2169,25 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
           // before a model starts. Delivery still re-reads the authoritative thread.
           rootContent = optional ? await Promise.race([context, new Promise((resolve) => {
             contextTimer = setTimeout(() => {
+              contextUnavailable = true
               log(`mention optional context pending channel=${cid} message=${messageId} — continuing with verified recipient`)
               resolve('')
             }, 1000)
           })]) : await context
         }
         catch (error) {
+          contextUnavailable = true
           if (!preliminary.explicitSelf && !memory.has(threadControlKey(cid, parent), 'active')) throw error
           log('optional root context unavailable; preserving verified recipient: ' + (error?.message || error))
         }
         finally { clearTimeout(contextTimer) }
       }
+      // Deletion may arrive during identity/history I/O, before there is a
+      // queue entry for cancellation to find. Recheck at the admission boundary.
+      if (memory.has(`deleted-message:${Number(cid)}:${Number(messageId)}`, 'deleted') || parent != null && memory.has(`deleted-message:${Number(cid)}:${Number(parent)}`, 'deleted')) return { status: 'ignored-deleted' }
       if (!stopping) {
         if (!irrelevant) log(`mention timing intake=${Math.round(performance.now() - intakeStartedAt)}ms source=${k} channel=${cid} message=${messageId}`)
-        return routeEvent('agent:mention', { ...eventData, _sourceEvent: k, _threadRootContent: rootContent })
+        return routeEvent('agent:mention', { ...eventData, _sourceEvent: k, _threadRootContent: rootContent, _contextUnavailable: contextUnavailable })
       }
     }).catch((error) => { log('mention thread verification failed: ' + (error?.message || error)); return { status: 'retry' } })
       .finally(() => { if (mentionIntake.get(key) === next) mentionIntake.delete(key) })
@@ -2129,11 +2227,6 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
         log('agent:mention replay recovered for active owned thread')
       }
       const loopKey = cid != null && threadRoot != null ? peerTurnKey('channel', cid, threadRoot) : ''
-      if (peerMessage && loopKey && memory.has(loopKey, 'replied')) {
-        log('agent:mention ignored before model start (peer-loop-budget)')
-        return { status: 'ignored-peer-loop' }
-      }
-      if (!peerMessage && loopKey) memory.remember({ key: loopKey, kind: 'peer-turn', state: 'human', summary: text, refs: { channelId: Number(cid), threadId: Number(threadRoot) } })
       const target = classifyConversationTarget(msg, [...selfAliases], { threadOwned })
       if (target.action === 'ignore') {
         log('agent:mention ignored before model start (' + target.reason + ')')
@@ -2154,6 +2247,11 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
         }
         return
       }
+      if (peerMessage && loopKey) {
+        const meta = admitPeerTurn(memory.get(loopKey), text, target)
+        if (!meta) { log('agent:mention ignored before model start (peer-loop-budget)'); return { status: 'ignored-peer-loop' } }
+        memory.remember({ key: loopKey, kind: 'peer-turn', state: 'reserved', meta })
+      } else if (loopKey) memory.remember({ key: loopKey, kind: 'peer-turn', state: 'human', summary: text, refs: { channelId: Number(cid), threadId: Number(threadRoot) } })
       if (cid != null && threadRoot != null) activateThread(cid, threadRoot, text)
       memory.remember({ key: sourceKey, kind: 'mention', state: 'received', summary: text, refs: { channelId: cid, threadId: threadRoot, messageId: mid } })
       try { contextService.observe({ name: 'list_message_thread', args: { channel_id: cid, message_id: threadRoot }, result: { ...msg, id: mid, content: String(msg.content || msg.body || msg.text || '') } }) }
@@ -2162,10 +2260,11 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
       // redirect can cancel its process. The watcher delivers the final answer
       // for every runtime after an authoritative last-moment thread check.
       const conversationDelivery = (stage = 'reply', skipIfAnyAgentReply = stage !== 'result', allowChannelMessaging = false) => cid != null
-        ? { key: `reply:${sourceKey}:${stage}`, channelId: Number(cid), parentId: threadRoot, skipIfAnyAgentReply, sourceKey, sourceMessageId: mid, watcherOwned: true, allowChannelMessaging, peerLoopKey: peerMessage ? loopKey : '' }
+        ? { key: `reply:${sourceKey}:${stage}`, channelId: Number(cid), parentId: threadRoot, skipIfAnyAgentReply, sourceKey, sourceMessageId: mid, sourceMessage: msg, contextUnavailable: raw._contextUnavailable, watcherOwned: true, allowChannelMessaging, peerLoopKey: peerMessage ? loopKey : '' }
         : null
       // Under-the-hood model control from chat (view / switch the model the agent runs).
       const mcmd = cid != null ? parseModelCmd(text) : null
+      if (peerMessage && mcmd && !mcmd.report) { log('Peer agent cannot change local model configuration'); return }
       if (mcmd) {
         refreshModelSettings()
         const thread = threadRoot != null ? `, parent_id ${threadRoot}` : ''

package/studio/app.mjs

@@ -15,7 +15,7 @@ export function normalizeStatus(value, fallback = 'observed') {
   if (['active', 'running', 'started', 'ready', 'in_progress', 'working', 'online', 'preflight'].includes(status)) return 'active';
   if (['queued', 'pending', 'waiting'].includes(status)) return 'queued';
   if (['completed', 'complete', 'finished', 'done', 'success', 'succeeded', 'ok'].includes(status)) return 'completed';
-  if (['failed', 'failure', 'error', 'rejected', 'rate_limited'].includes(status)) return 'failed';
+  if (['failed', 'failure', 'error', 'rejected', 'rate_limited', 'handoff_error'].includes(status)) return 'failed';
   if (['cancelled', 'canceled', 'aborted', 'interrupted'].includes(status)) return 'cancelled';
   if (['offline', 'stopped', 'disconnected', 'exited'].includes(status)) return 'offline';
   if (['skipped', 'recovering', 'idle', 'blocked', 'timeout', 'continued'].includes(status)) return status;
@@ -115,7 +115,7 @@ export function deriveModel(input) {
       const prior = runtimes.get(processKey) || {};
       runtimes.set(processKey, {
         ...prior, ...data, id: processKey, type: 'process', agent: event.agent, event,
-        name: text(data.runtime || prior.name || data.provider || 'Coding runtime'),
+        name: runtimeLabel({ ...prior, ...data }),
         pid: Number.isInteger(data.runtimePid) && data.runtimePid > 0 ? data.runtimePid : prior.pid ?? null,
         status: eventStatus(event), lastSeen: event.timestamp,
       });
@@ -181,15 +181,22 @@ export function taskActivityCycles(model, selectedCycle) {
   return [...latest.values()].sort((a, b) => agentId(a.agent).localeCompare(agentId(b.agent)));
 }
 
+export function runtimeLabel(data = {}) {
+  return data.lane === 'reply' ? 'Reply runtime' : data.lane === 'work' ? 'Coding runtime' : 'Agent runtime';
+}
+
 export function eventTitle(event) {
   const data = record(event?.data);
+  if (['process.started', 'process.ready', 'process.stopped'].includes(event?.type)) {
+    const phase = event.type === 'process.started' ? 'starting' : event.type === 'process.stopped' ? 'stopped' : data.status === 'idle' ? 'idle' : 'ready';
+    return `${runtimeLabel(data)} ${phase}`;
+  }
   const titles = {
     'runtime.started': 'Watcher connected', 'runtime.heartbeat': 'Watcher heartbeat', 'runtime.stopped': 'Watcher stopped',
     'cycle.queued': 'Cycle queued', 'cycle.started': 'Cycle started', 'cycle.finished': 'Cycle finished',
-    'cycle.continued': 'Continued in coding workspace',
+    'cycle.continued': 'Coding continuation queued',
     'cycle.completed': 'Cycle completed', 'cycle.cancelled': 'Cycle cancelled', 'cycle.failed': 'Cycle failed',
     'plan.updated': 'Plan updated', 'output.progress': 'Progress update', 'output.final': 'Final response',
-    'process.started': 'Coding runtime starting', 'process.ready': 'Coding runtime ready', 'process.stopped': 'Coding runtime stopped',
   };
   if (text(event?.type).startsWith('tool.')) {
     const action = event.type === 'tool.started' ? 'Started' : ['tool.finished', 'tool.completed'].includes(event.type) ? 'Finished' : 'Updated';
@@ -767,7 +774,7 @@ function initializeStudio() {
     inspector.replaceChildren(inspectorHeader('Process details', process.name, agentName(process.agent), process.status));
     const section = detailSection('Process record', 'terminal');
     section.append(detailGrid([
-      ['Kind', process.type === 'watcher' ? 'BYO watcher' : 'Coding runtime'], ['Provider', process.agent.provider || process.provider],
+      ['Kind', process.type === 'watcher' ? 'BYO watcher' : runtimeLabel(process)], ['Provider', process.agent.provider || process.provider],
       ['PID', process.pid || (process.status === 'demo' ? 'Simulated' : 'Not reported'), true],
       ['Last event', fullTime(process.lastSeen)], ['Session', process.sessionId, true], ['Run ID', process.runId || process.event?.runId, true],
     ]));
@@ -802,6 +809,7 @@ function initializeStudio() {
       return;
     }
     $('demo-badge').hidden = !state.snapshot.demo;
+    $('open-agent-connect').disabled = state.snapshot.demo;
     for (const button of document.querySelectorAll('[data-view]')) {
       const selected = button.dataset.view === state.view; button.classList.toggle('is-selected', selected); button.setAttribute('aria-pressed', String(selected));
     }
@@ -813,6 +821,55 @@ function initializeStudio() {
   }
 
   $('server-address').textContent = location.host;
+  let connectingAgent = false;
+  const credentialFields = ['name', 'identifier', 'apiKey', 'backend', 'mcpUrl', 'wsUrl', '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;
+    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' : '';
+      $('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.';
+      $('agent-connect-error').hidden = false;
+    }
+  });
+  $('agent-connect-form').addEventListener('submit', async event => {
+    event.preventDefault();
+    if (connectingAgent) return;
+    connectingAgent = true;
+    $('save-agent-connect').disabled = true;
+    $('close-agent-connect').disabled = true;
+    $('save-agent-connect').textContent = 'Verifying…';
+    $('agent-connect-error').hidden = true;
+    try {
+      const input = Object.fromEntries(credentialFields.map(key => [key, $('connect-' + key).value.trim()]));
+      const result = await settingsFetch('/api/agents/connect', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input) });
+      $('agent-connect-dialog').close();
+      state.selectedAgent = result.identifier;
+      state.agentSearch = ''; $('agent-search').value = '';
+      toast('Agent connected. Choose Start watcher when your runtime is installed and signed in.');
+      receive(await settingsFetch('/api/snapshot'), true);
+    } catch (error) {
+      $('agent-connect-error').hidden = false;
+      $('agent-connect-error').textContent = error.message;
+    } finally {
+      connectingAgent = false;
+      $('save-agent-connect').disabled = false;
+      $('close-agent-connect').disabled = false;
+      $('save-agent-connect').textContent = 'Verify and connect';
+    }
+  });
+
   $('open-model-settings').addEventListener('click', () => {
     const agent = state.model.agents.find(agent => agentId(agent) === state.selectedAgent);
     if (agent?.settingsEditable) void openModelSettings(agent);

package/studio/guide.html

@@ -58,7 +58,7 @@
             <h2>Show your agents</h2>
             <p>A <strong>watcher</strong> is the local program that listens for assignments and messages, then starts your coding agent when work arrives. Studio displays what the watcher records.</p>
             <ol>
-              <li>Connect your agent using the setup command provided by your OpenVisio team. If you already connected it, keep that setup.</li>
+              <li>After registering your agent in OpenVisio, choose <strong>Copy credentials</strong>. In Studio, choose <strong>Connect agent</strong>, paste the credentials, and choose <strong>Verify and connect</strong>. You can also enter the fields individually or use the optional terminal command. If you already connected it, keep that setup.</li>
               <li>Select the agent in Studio and choose <strong>Start watcher</strong>. Studio installs its background watcher and starts it with the current package and saved model settings.</li>
               <li>Return to Studio. Your agent should appear in the sidebar. Select its name to see its activity.</li>
             </ol>

package/studio/index.html

@@ -60,13 +60,31 @@
       <main id="workspace" class="workspace" tabindex="-1">
         <header class="page-header">
           <div><div class="eyebrow">Runtime overview <span id="demo-badge" class="badge demo-badge" hidden>Demo data</span></div><h1>Agent studio</h1><p class="page-description">See what your agents are doing, as it happens.</p></div>
-          <div class="header-actions"><a class="button header-documentation" href="/guide"><svg class="icon" aria-hidden="true"><use href="#i-book"/></svg>Documentation</a><span id="connection-status" class="connection-status" role="status"><span class="dot"></span><span>Connecting</span></span><button id="pause-button" class="button" type="button" aria-pressed="false"><svg class="icon" aria-hidden="true"><use href="#i-pause"/></svg><span>Pause view</span></button></div>
+          <div class="header-actions"><button id="open-agent-connect" class="button primary" type="button" disabled>Connect agent</button><a class="button header-documentation" href="/guide"><svg class="icon" aria-hidden="true"><use href="#i-book"/></svg>Documentation</a><span id="connection-status" class="connection-status" role="status"><span class="dot"></span><span>Connecting</span></span><button id="pause-button" class="button" type="button" aria-pressed="false"><svg class="icon" aria-hidden="true"><use href="#i-pause"/></svg><span>Pause view</span></button></div>
         </header>
         <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>
         </section>
+        <dialog id="agent-connect-dialog" aria-labelledby="agent-connect-title">
+          <form id="agent-connect-form" class="model-settings-form" autocomplete="off">
+            <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-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-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="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>