openvisio-agent 0.19.11 → 0.20.0

package/README.md

@@ -2,6 +2,8 @@
 
 Connect your coding agent (**Claude Code, Codex, or OpenCode**) to an [OpenVisio](https://openvisio.app) 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.
+
 ```bash
 npx -y openvisio-agent@latest connect ovs_YOURCODE --host https://your-openvisio.app --name "Ada"
 ```
@@ -64,13 +66,13 @@ Backend/BYO watchers reconcile immediately whenever the process starts or the We
 
 The backend MCP may be stateful or stateless. A successful initialize response without `Mcp-Session-Id` is accepted as stateless, so OpenCode agents do not stop with “MCP initialize returned no session id.” Each OpenCode lane keeps its MCP identity in a private per-agent config directory while the repository is supplied separately with `--dir`; stale workspace configuration therefore cannot swap one agent's credentials for another's. The generated remote configuration sends the agent headers directly, disables OAuth probing, and backend cycles never request relay-only inbox calls or MCP resource-discovery tools in place of team actions.
 
-Codex BYO agents follow the repository's normative runtime specification in `docs/CODEX_BYO_AGENT_SPEC.md`: one WebSocket identity, independent Sol reply/work lanes, authoritative `get_ticket` verification for assignments, REST-backed in-app activity, persistent replay suppression, and runtime evidence gates before completion. Maintainers must run `npm run certify` before publishing.
+Codex BYO agents follow the repository's normative runtime specification in `docs/CODEX_BYO_AGENT_SPEC.md`: one WebSocket identity, independent reply/work queues, authoritative `get_ticket` verification for assignments, silent transient activity, persistent replay suppression, and runtime evidence gates before completion. Maintainers must run `npm run certify` before publishing.
 
-An `agent:mention` event only wakes the watcher; the actual source message is checked before any model starts. An explicit tag establishes durable ownership of that thread, so later human follow-ups remain addressed to the agent without another @mention. Messages redirected to another agent and unaddressed agent chatter stay silent, while a direct stand-down cancels queued/running work and releases ownership for that thread. The watcher does not broadcast working, thinking, or typing presence updates. Claude and OpenCode may add one concrete progress update after work begins, but must continue and post a distinct verified result or blocker afterward; Codex keeps cancellation-safe delivery watcher-owned and renders the verified final answer once.
+Both `agent:mention` and organization `channel:message` events pass through the same source-recipient, ownership, and deduplication checks before any model starts. The watcher subscribes only to the organization verified from its own authenticated agent profile and restores that subscription after reconnect. Self-authored source messages are ignored; embedded old agent replies cannot hide a human follow-up. An explicit tag establishes durable ownership of that thread, so later human follow-ups remain addressed to the agent without another @mention. Messages redirected to another agent and unaddressed agent chatter stay silent, while a direct stand-down cancels queued/running work and releases ownership for that thread. Concrete roots verified as belonging to someone else have a bounded one-minute cache; missing authors and failed reads remain immediately retryable. The watcher does not broadcast working, thinking, or typing presence updates. Claude and OpenCode may add one concrete progress update after work begins, but must continue and post a distinct verified result or blocker afterward; Codex keeps cancellation-safe delivery watcher-owned and renders the verified final answer once.
 
 Ticket references follow the board UI: BYO agents use the project-scoped slug, such as `OVS-57`, in messages, comments, PR descriptions, blockers, and results. Numeric `project_id` and `ticket_id` values remain internal MCP arguments and are never used as human-facing ticket names. If an older backend omits the slug, the agent uses the ticket title rather than inventing one.
 
-Claude uses Haiku for routine coordination and Sonnet for repository work. Codex uses `gpt-5.6-sol` for every cycle, including messages, mentions, triage, board movement, MCP calls, and coding. This intentionally favors reliability and consistent tool use over the cheaper Codex tiers.
+Claude uses Haiku for routine coordination and Sonnet for repository work. Codex defaults to `gpt-5.6-sol`; configured code and chat models are preserved independently.
 
 ```bash
 openvisio-agent watch --name ada                 # run in this terminal
@@ -103,7 +105,7 @@ Do not chase auto-changing watcher PIDs. `openvisio-agent stop --name <agent>` u
 
 - **No opaque script.** You run a named, versioned npm package you can read here and on [npmjs.com](https://www.npmjs.com/package/openvisio-agent).
 - **Single-use code.** The `ovs_` code is exchanged once for a key; a leaked code is already spent.
-- **Least privilege.** Chat mode exposes only the `openvisio-team` MCP tools. Codex private-repository pushes require an explicit per-repository opt-in and go through a no-argument `agent/*`-only helper; merges and protected-branch pushes remain unavailable.
+- **Least privilege.** Chat mode exposes only the `openvisio-team` MCP tools. Coding setup grants routine PR publishing inside its workspace through a no-argument `agent/*`-only helper. Repositories outside that workspace need an exact repository grant. The helper cannot merge or push protected branches.
 - **Local secrets.** Your agent key lives in `~/.openvisio/` with `600` permissions — never printed, never committed.
 
 ## Requirements
@@ -125,3 +127,31 @@ rm -rf ~/.openvisio
 ```
 
 MIT
+
+## Agent studio
+
+Agent Studio is available in `0.20.0` and later. Open the local viewer with:
+
+```bash
+npx -y openvisio-agent@latest studio
+```
+
+To run from source, see [the checkout instructions](USER_GUIDE.md#run-studio-from-this-checkout).
+
+Select **User guide** in Studio for a local, printable guide to controls and statuses. Start with [the walkthrough](USER_GUIDE.md#open-agent-studio) if you have not used the viewer before.
+
+Studio opens `http://127.0.0.1:4317` and follows the local agents' activity live. Select an agent or cycle to inspect its emitted plan, tool calls, command previews, file locations, progress messages, final result, and process status. The timeline distinguishes queued, running, completed, canceled, and failed work. Plans appear only when the runtime emits an explicit plan; internal reasoning is not recorded.
+
+```bash
+openvisio-agent studio --demo       # labeled sample activity; no model calls
+openvisio-agent studio --no-open    # print the URL without opening a browser
+openvisio-agent studio --port 0     # choose an available local port
+```
+
+Watchers running this version record bounded, credential-redacted activity under `~/.openvisio/observability`. Update and restart an older watcher once to start recording; its earlier plans and tool activity cannot be reconstructed. Closing Studio leaves the agents running. Studio uses local files and a loopback listener; it does not require a workspace or provider login. `--state-dir <dir>` selects an isolated watcher's state directory for local testing.
+
+## Reliability scenarios
+
+`npm test` includes the executable BYO scenario catalogue. `npm run test:scenarios -- --report /tmp/byo-results.json` writes every case, result, category, and duration. Cases cover routing, runtime lifecycle, transport, memory, authorization, and complete watcher sequences against simulated service/runtime boundaries. They do not invoke paid models or mutate a live workspace.
+
+The watcher now stores pending threaded replies before posting and retries their authoritative delivery checks without rerunning the model. Distinct source message IDs remain distinct requests even when their text is identical. Stable agent IDs take precedence over display names at every assignment gate.

package/USER_GUIDE.md

@@ -0,0 +1,174 @@
+# Your first OpenVisio agent
+
+Connect your coding agent to your team, let it handle assigned work, and follow its progress in Agent Studio.
+
+Already connected? Jump to [start your watcher](#start-your-watcher), [open Agent Studio](#open-agent-studio), or [solve a problem](#solve-a-problem).
+
+## Before you begin
+
+You need Node.js **22.13 or newer**, access to your OpenVisio team, and a supported coding agent: Claude Code, Codex, or OpenCode. Authenticate your chosen coding agent on this machine before asking it to work. Your provider’s usual usage limits and charges apply when the agent runs.
+
+Check your installed versions in a terminal:
+
+```sh
+node --version
+openvisio-agent --version
+```
+
+If `openvisio-agent` is not installed, install the published package:
+
+```sh
+npm install -g openvisio-agent@latest
+```
+
+**Studio availability:** Agent Studio requires `openvisio-agent` version `0.20.0` or newer. Update an older installation with the command above, or follow [run Studio from this checkout](#run-studio-from-this-checkout).
+
+## Connect to your team
+
+1. In OpenVisio, open **Agents** and choose the connection flow for your agent.
+2. Select your coding runtime and copy the setup command OpenVisio provides. It contains the correct team address and connection details; use it as supplied.
+3. Run the command in your terminal. Keep the agent name handy; the examples below use `ada`.
+4. Read the command’s output. Some setups install a background watcher automatically. Others print a command for starting it yourself.
+
+Treat the setup command and saved credentials as private. If a one-time setup code expires or was already used, obtain a new command from OpenVisio. Do not paste agent credentials into team messages or support reports.
+
+Coding mode is enabled by default for backend connections. The agent can handle assigned repository work in its configured workspace, push an `agent/*` branch, and open a pull request. The default workspace is `~/openvisio-workspace`. Use the setup command’s `--workspace /path/to/workspace` option to choose another location, or `--chat-only` for chat and ticket work without local coding.
+
+For advanced connection options, see the [command reference](README.md#what-it-does).
+
+## 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.
+
+If setup already started a background watcher, leave it running. Otherwise, replace `ada` with your configured agent name and run:
+
+```sh
+openvisio-agent watch --name ada
+```
+
+Keep this terminal open. For a service that starts at login on macOS or Linux, use:
+
+```sh
+openvisio-agent watch --name ada --install
+```
+
+Use one watcher per agent identity. To stop the named watcher and its background service:
+
+```sh
+openvisio-agent stop --name ada
+```
+
+Stopping a watcher interrupts its active work. When you are ready to resume, run the appropriate `watch` command again.
+
+## Give the agent work
+
+- **Ask a question:** mention the agent in an OpenVisio channel, such as “@Ada, what is the status of the login fix?”
+- **Assign repository work:** assign an actionable ticket to the agent in a project with a linked codebase. Include the problem, expected behavior, and how the result should be checked.
+- **Continue a conversation:** reply in the same thread. Keep follow-up instructions concrete, such as “The new test fails on an empty email address; please fix that case.”
+
+Replies stay in their source thread. New completion messages use the agent’s dedicated channel. Check the ticket and any linked pull request for delivered results. A progress message describes ongoing work; wait for the final result or blocker.
+
+## Open Agent Studio
+
+In another terminal, using a Studio-capable installation:
+
+```sh
+openvisio-agent studio
+```
+
+The command opens a local browser page, usually at `http://127.0.0.1:4317`. Use the exact address printed in your terminal. Studio reads activity on this machine; it does not start agents or require a provider login of its own.
+
+To explore sample activity without connecting an agent:
+
+```sh
+openvisio-agent studio --demo
+```
+
+The demo makes no model calls. Close it with `Ctrl+C` in its terminal and run Studio again without `--demo` to see your own agents.
+
+### Find a result
+
+1. Select an agent in the sidebar.
+2. Select **Cycles**. A cycle is a group of actions for one unit of work.
+3. Search for the ticket reference, such as `OVS-57`, and select the matching row.
+4. Review its **Outcome**, tools, and **Final response**. Expand **Cycle history** for the recorded sequence.
+
+Use **Activity** for individual events and **Processes** for watcher and runtime records. A completed tool is one completed step, not necessarily a completed task.
+
+**Pause view** freezes the page while agents keep working. **Resume view** shows the latest available snapshot. Selecting a row turns **Follow latest** off; re-enable it to follow new activity.
+
+Select **User guide** in Studio for the full guide to controls, status meanings, keyboard navigation, history, and troubleshooting. The guide is served locally at `/guide`, works without JavaScript, and supports browser printing.
+
+### Understand what you see
+
+| Label | Meaning and next step |
+| --- | --- |
+| Live | Your browser is connected to Studio. Each watcher has its own connection status. |
+| Queued / Active | Work is waiting or running in the current watcher run. |
+| Completed | The selected action or cycle reported completion. Review the final result and ticket. |
+| Blocked / Failed / Timed out | Read the outcome and watcher log. Resolve the stated cause before requesting more work. |
+| Offline | The watcher stopped reporting or restarted. An unfinished cycle has no known final outcome in the available history. |
+| No explicit plan recorded | No plan was provided in the available history. This alone is not a failure. |
+| PID not reported | The provider did not supply its process identifier. Studio cannot count it as a known operating-system process. |
+| Simulated | Demo activity, with no real work running. |
+
+## Update an older watcher
+
+Installing a new package does not update a watcher that is already running. Update the package and restart each named watcher when you are ready to interrupt its work:
+
+```sh
+npm install -g openvisio-agent@latest
+openvisio-agent stop --name ada
+openvisio-agent watch --name ada --install
+```
+
+Use `watch --name ada` without `--install` if you prefer a foreground terminal or your operating system does not support the background service.
+
+Only new activity from an updated watcher appears in Studio. Earlier plans, tool calls, and results cannot be reconstructed from an older watcher.
+
+## Solve a problem
+
+| Problem | What to do |
+| --- | --- |
+| `studio` is not recognized | Check the installed version. Use a Studio-capable release or the checkout instructions below. |
+| Browser did not open | Run `openvisio-agent studio --no-open` and open the URL it prints. |
+| Port is already in use | Run `openvisio-agent studio --port 0` to choose an available port. |
+| Studio shows no agents | Confirm the watcher runs under the same local account. Studio reads `~/.openvisio` by default. |
+| “Restart watcher to connect” | Update and restart that watcher using the steps above. |
+| No matching activity | Clear search, kind, and status filters, then select All agents. |
+| Reconnecting | Keep Studio running in its terminal. The browser automatically reconnects when the server returns. |
+| Agent is blocked | Read its outcome and ticket. Studio is a viewer; approvals and fixes happen in the relevant setup, repository, or team workflow. |
+| Result is missing | Check the original ticket and channel. Studio shows recent, limited history and can omit older or oversized records. |
+
+For a macOS background service, the watcher log is at `~/.openvisio/<agent>.log`. For Linux, use `journalctl --user -u openvisio-<agent>`. Foreground watchers print to their terminal.
+
+When reporting a problem, include the package version, operating system, relevant ticket reference, what you expected, and the redacted error. Review logs and screenshots for private project details before sharing them.
+
+## Read comfortably
+
+Use `Tab` and `Shift+Tab` to move through controls, `Enter` to activate buttons or links, and `Space` to toggle checkboxes. Use the skip link to reach the activity area and your screen reader’s headings or landmarks to find selected details. Pause the view when reading long output. Browser zoom enlarges the interface, and details move below the list on narrow screens.
+
+## Local history and privacy
+
+Studio reads bounded journals in `~/.openvisio/observability`. It serves up to 500 recent events, subject to file and byte limits. Journals rotate, long text is shortened, and bursts may drop records. Use the team’s ticket and channel history for delivered results.
+
+The journal excludes private reasoning and raw tool payloads and redacts known credentials and recognizable secret formats. Public progress and file paths may still contain private project information. Keep the local state directory private and review exports before sharing them.
+
+Studio listens only on this machine. Closing it leaves agents running. Running watchers continue to contact their team and coding provider as configured.
+
+## Run Studio from this checkout
+
+From the repository root, install this package’s declared dependencies, then open the demo:
+
+```sh
+npm ci --prefix packages/openvisio-agent
+node packages/openvisio-agent/bin/cli.mjs studio --demo
+```
+
+To view local activity, omit `--demo`. To record activity with this checkout’s watcher, stop an older watcher for that identity first, then run:
+
+```sh
+node packages/openvisio-agent/bin/cli.mjs watch --name ada
+```
+
+Keep the watcher and Studio in separate terminals. The `studio --state-dir /path/to/state` option changes the directory the viewer reads; it does not reconfigure a watcher or move its files.

package/bin/cli.mjs

@@ -28,6 +28,7 @@ Usage:
   openvisio-agent connect --backend <url> --key <api-key> --id <identifier> [--name "<agent>"] [--ws <wss-url>] [--mcp-url <url>] [--agent claude|codex|opencode]
   openvisio-agent watch   --name <agent> [--install] [--workspace <dir>] [--chat-only] [--model <m>] [--chat-model <m>] [--debug]
   openvisio-agent stop    --name <agent>
+  openvisio-agent studio  [--port <number>] [--no-open] [--demo]
   openvisio-agent authorize-pr-push [--repo <dir>]
   openvisio-agent push-pr-branch
   openvisio-agent revoke-pr-push [--repo <dir>]
@@ -81,6 +82,13 @@ stop
   remaining watcher with that exact --name and clears its stale lock. Use this
   instead of killing changing PIDs: openvisio-agent stop --name Alex
 
+studio
+  Opens a local live viewer for agent cycles, plans, tool calls, coding progress,
+  and process status. Uses http://127.0.0.1:4317 by default; --port 0 selects an
+  available port. --no-open prints the URL without opening a browser. --demo
+  shows simulated activity without starting agents. --state-dir <dir> selects
+  an isolated watcher state directory. Closing the viewer leaves agents running.
+
 Use --channel <id> during connect to select the dedicated channel for new threads.
 
 PR publishing is enabled during connect for the coding workspace, including
@@ -310,6 +318,7 @@ async function main() {
   const rest = parseFlags(argv.slice(1))
   if (cmd === 'connect') return runConnect(rest)
   if (cmd === 'watch') return (await import('../src/watch.mjs')).runWatch(rest)
+  if (cmd === 'studio') return (await import('../src/studio-cli.mjs')).runStudio(rest)
   if (cmd === 'stop') {
     const name = String(rest.flags.name || rest.positional[0] || '')
     if (!name) fail('Missing agent name.\n  Usage: openvisio-agent stop --name <agent>')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.19.11",
+  "version": "0.20.0",
   "description": "Connect Claude Code, Codex, or OpenCode to an OpenVisio team \u2014 MCP tools + optional autonomy \u2014 in one command.",
   "type": "module",
   "bin": {
@@ -8,13 +8,17 @@
   },
   "scripts": {
     "test": "node --test",
-    "certify": "node scripts/certify.mjs"
+    "certify": "node scripts/certify.mjs",
+    "test:scenarios": "node scripts/run-scenarios.mjs"
   },
   "files": [
     "bin",
     "scripts",
+    "scenarios",
+    "studio",
     "src",
-    "README.md"
+    "README.md",
+    "USER_GUIDE.md"
   ],
   "engines": {
     "node": ">=22.13"

package/scenarios/index.mjs

@@ -0,0 +1,16 @@
+import { scenarios as routing } from './routing.scenarios.mjs'
+import { scenarios as runtime } from './runtime.scenarios.mjs'
+import { scenarios as transport } from './transport.scenarios.mjs'
+import { scenarios as workspace } from './workspace.scenarios.mjs'
+
+export const scenarios = [...routing, ...runtime, ...transport, ...workspace]
+export function validateCatalogue() {
+  const ids = new Set()
+  for (const entry of scenarios) {
+    if (!entry.id || ids.has(entry.id) || !entry.category || !entry.description || typeof entry.run !== 'function') {
+      throw new Error(`Invalid or duplicate scenario: ${entry.id}`)
+    }
+    ids.add(entry.id)
+  }
+  if (ids.size <= 1000) throw new Error(`Expected over 1000 scenarios; found ${ids.size}`)
+}