openvisio-agent 0.3.7 → 0.4.0

package/bin/cli.mjs

@@ -26,7 +26,7 @@ Connect your coding agent to an OpenVisio team.
 Usage:
   openvisio-agent connect <ovs_code> --host <url> [--name "<agent>"] [--mcp-url <url>]
   openvisio-agent connect --backend <url> --key <api-key> --id <identifier> [--name "<agent>"] [--ws <wss-url>] [--mcp-url <url>]
-  openvisio-agent watch   --name <agent> [--install] [--workdir <repo>] [--debug]
+  openvisio-agent watch   --name <agent> [--install] [--workspace <dir>] [--chat-only] [--debug]
   openvisio-agent --help | --version
 
 connect
@@ -45,14 +45,23 @@ connect --backend
                      — enables real-time autonomy (task:assigned / agent:mention).
     --mcp-url <url>  registers the openvisio-team MCP so the agent has tools to ACT
                      on those events. Needs Node >= 21 for the WebSocket.
-    --workdir <repo> the always-on listener may do real coding on a branch there.
+    --workspace <dir> where the agent works. CODE mode is ON BY DEFAULT — it finds
+                     the org's repos here (cloning any it doesn't have yet), branches,
+                     pushes its agent/* branch and opens PRs. Defaults to
+                     ~/openvisio-workspace; point it at an existing clones folder to
+                     reuse those. (--workdir is an accepted alias.)
+    --chat-only      disable code work — chat/ticket tools only.
     --no-service     skip the background service — just save config + print the
                      watch commands to run yourself.
 
 watch
-  Runs the event-driven autonomy loop (reply to mentions, pick up tickets). Add
-  --install to run it in the background on login. Add --workdir <repo> to let it do
-  real work on a git branch (never pushes).
+  Runs the event-driven autonomy loop (reply to mentions, pick up tickets). CODE
+  mode is ON BY DEFAULT: the agent finds the org's repos in its workspace
+  (~/openvisio-workspace, cloning any it doesn't have yet), branches, commits, pushes
+  its agent/* branch, opens PRs, then circles back with the PR link and @mentions the
+  requester — never touching main/master, never force-pushing or merging. No per-repo
+  setup needed. Use --workspace <dir> to relocate it (e.g. an existing clones folder),
+  --chat-only to disable code work, and --install to run in the background on login.
 
 Docs: https://www.npmjs.com/package/openvisio-agent`
 
@@ -100,16 +109,19 @@ async function runConnect({ positional, flags }) {
   // A scoped MCP config (for the watcher's --strict-mcp-config) + a saved profile.
   const mcpCfg = mcpConfigPath(slug)
   writeJson(mcpCfg, { mcpServers: { 'openvisio-team': { type: 'http', url: mcpUrl, headers: { Authorization: `Bearer ${key}` } } } }, true)
-  writeJson(configPath(slug), { host: stripSlash(host), key, mcpUrl, name, slug, mcpConfig: mcpCfg }, true)
+  const wsWorkdir = flags.workdir === true ? process.cwd() : flags.workdir ? String(flags.workdir) : flags.workspace ? String(flags.workspace) : ''
+  writeJson(configPath(slug), { host: stripSlash(host), key, mcpUrl, name, slug, mcpConfig: mcpCfg, ...(wsWorkdir ? { workspace: wsWorkdir } : {}), ...(flags['chat-only'] ? { chatOnly: true } : {}) }, true)
 
   ok(`Connected "${name}" to ${host}.`)
   info()
   info('Claude Code now has the openvisio-team tools. Run  /mcp  in Claude Code to confirm.')
   info()
-  info('To let it work on its own (reply to mentions, pick up tickets):')
-  info(`  openvisio-agent watch --name ${slug}                    # run now, in this terminal`)
-  info(`  openvisio-agent watch --name ${slug} --install          # run in the background on login`)
-  info(`  openvisio-agent watch --name ${slug} --workdir <repo>   # allow real coding on a branch`)
+  info('To let it work on its own (reply to mentions, pick up tickets, AND do real')
+  info('coding — it clones/branches/pushes and opens PRs out of the box):')
+  info(`  openvisio-agent watch --name ${slug}                       # run now, in this terminal`)
+  info(`  openvisio-agent watch --name ${slug} --install             # background, auto-start on login`)
+  info(`  openvisio-agent watch --name ${slug} --workspace <dir>     # reuse an existing clones folder`)
+  info(`  openvisio-agent watch --name ${slug} --chat-only           # disable code work (chat/tickets only)`)
 }
 
 // Backend mode — for agents created against the OpenVisio ORG BACKEND
@@ -140,6 +152,13 @@ async function runConnectBackend({ flags }) {
   const name = (flags.name && String(flags.name)) || 'backend-agent'
   const slug = slugify(name)
 
+  // Code workspace preference (optional). CODE mode is on by default; this only
+  // pins WHERE the agent works. Persisted so the always-on `watch` reuses it.
+  const chatOnly = !!flags['chat-only']
+  const workdir = flags.workdir === true ? process.cwd()
+    : flags.workdir ? String(flags.workdir)
+    : flags.workspace ? String(flags.workspace) : ''
+
   // Optional real-time autonomy: --ws is the org's API-Gateway WS base (same value
   // as the frontend's NEXT_PUBLIC_BACKEND_WS_URL). --mcp-url gives the agent a tool
   // surface so WS events (task:assigned / agent:mention) can drive a Claude cycle.
@@ -157,7 +176,7 @@ async function runConnectBackend({ flags }) {
     writeJson(mcpConfig, { mcpServers: { 'openvisio-team': { type: 'http', url: mcpUrl, headers: { 'x-agent-api-key': apiKey, 'x-agent-identifier': identifier } } } }, true)
   }
 
-  writeJson(configPath(slug), { mode: 'backend', backend, apiKey, identifier, name, slug, wsUrl, mcpUrl, mcpConfig }, true)
+  writeJson(configPath(slug), { mode: 'backend', backend, apiKey, identifier, name, slug, wsUrl, mcpUrl, mcpConfig, ...(workdir ? { workspace: workdir } : {}), ...(chatOnly ? { chatOnly: true } : {}) }, true)
   // A sourceable env file, matching the setup snippet OpenVisio shows.
   const envPath = join(OV_DIR, `${slug}.env`)
   mkdirSync(OV_DIR, { recursive: true })
@@ -188,7 +207,6 @@ async function runConnectBackend({ flags }) {
   // Real-time autonomy IS the point of a backend agent: install the command and a
   // background service that auto-starts on login, so a mention is always caught —
   // no terminal left open, survives reboot. Opt out with --no-service.
-  const workdir = flags.workdir === true ? process.cwd() : (flags.workdir ? String(flags.workdir) : '')
   if (flags['no-service'] || process.platform === 'win32') {
     ensureAgentInstalled()
     info()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "Connect your coding agent (Claude Code) to an OpenVisio team — MCP tools + optional autonomy — in one command. No shell scripts.",
   "type": "module",
   "bin": {

package/src/lib.mjs

@@ -7,6 +7,12 @@ import { join } from 'node:path'
 import { mkdirSync, writeFileSync, readFileSync, chmodSync } from 'node:fs'
 
 export const OV_DIR = join(homedir(), '.openvisio')
+// The agent's default code WORKSPACE — a single dedicated root that holds the org's
+// repos as subfolders. Code mode is on by default and the agent clones missing
+// repos in here, so a coding assistant works out of the box with NO per-repo config
+// (override with --workdir/--workspace to point at an existing clones folder). Kept
+// separate from the user's own checkouts so the agent never stomps a working tree.
+export const DEFAULT_WORKSPACE = join(homedir(), 'openvisio-workspace')
 const IS_WIN = process.platform === 'win32'
 
 export function fail(msg) { console.error('✖ ' + msg); process.exit(1) }

package/src/watch.mjs

@@ -8,19 +8,76 @@ import { spawn, spawnSync } from 'node:child_process'
 import { writeFileSync, mkdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, dirname } from 'node:path'
-import { OV_DIR, readConfig, onPath, fail, ok, info, slugify, stripSlash, chmodSafe } from './lib.mjs'
+import { OV_DIR, DEFAULT_WORKSPACE, readConfig, onPath, fail, ok, info, slugify, stripSlash, chmodSafe } from './lib.mjs'
 import { connectAgentWs, assertWebSocket } from './ws.mjs'
 
 // Behaviour prompts. The openvisio-team MCP bridge requires the agent's
 // credentials as ARGUMENTS on every tool call — those are injected at runtime by
 // loopBackendWs (see credNote), NOT baked in here, so nothing needs hunting.
-const CYCLE = 'Run one OpenVisio autonomy cycle.'
-const CYCLE_FAST = 'New chat activity in OpenVisio. If a specific mention is given above, post that reply FIRST with mcp__openvisio-team__post_message. Then call poll_inbox and handle any .followUps (thread replies you are part of, even without an @mention) — ignore .tasks/.claimable. Post AT MOST ONE reply per channel: if the same person sent several nudges, answer them together in ONE post. HONESTY: your only tools are the openvisio-team chat/ticket tools — you cannot write code or touch other tools; if asked for work you have no tool for, say so plainly in one short message (or offer to file a ticket). Never invent progress. Reply in 1-3 sentences, no summary. Then stop.'
-const CODE_FULL = 'Run one OpenVisio autonomy cycle. Call get_marching_orders and poll_inbox. You have file + Bash tools and a git repo at your working directory FOR CODE WORK ONLY. For assigned tickets or mentions asking for real code work: FIRST "git checkout -B agent/work", make the changes with Read/Edit/Write, run tests if present, then "git add -A && git commit -m ...". NEVER git push, merge, or touch main. Then comment_ticket with a short summary + the branch name, and post a brief channel reply. Do NOT use Bash to find credentials — they are given to you. If you truly cannot (missing repo/specs), say so in one message — never fabricate.'
-const CODE_FAST = 'New chat activity in OpenVisio. If a specific mention is given above, post that reply FIRST with mcp__openvisio-team__post_message — do this before any Bash. Then poll_inbox and handle .followUps (thread replies you are part of, even without an @mention), AT MOST ONE reply per channel. Only if a message asks for real CODE work in your git repo, do it on a branch (checkout -B agent/work, edit, commit locally — never push/merge) and reply with the branch name. Bash is for git/tests ONLY, never for credentials. 1-3 sentences, no summary. Then stop.'
+//
+// Two recurring failures these prompts fix head-on: (1) the agent UNDER-READS its
+// own capabilities — says "I can't check a codebase" when it can — and (2) it
+// PROMISES work then stops, forcing the human to remind it to circle back. The
+// CHARTER blocks below assert the toolbox and mandate closing the loop in-cycle.
 
+// ── CHAT-ONLY agents (no --workdir): chat/ticket tools, no code surface. ──────
+const CHAT_CHARTER = [
+  'YOU ARE a connected agent in an OpenVisio team, running in CHAT-ONLY mode. Your tools are the openvisio-team chat/ticket tools (mcp__openvisio-team__*): post_message, poll_inbox, comment_ticket, react_message. You have NO file/Bash/git tools in this mode, so you cannot write code yourself.',
+  'WORK ETHIC — behave like a dependable teammate: never leave a promise dangling. Either ACT now (reply, or file a ticket) or say plainly you can\'t and offer to file a ticket / tag a coding agent who can. Never invent progress. Close the loop every cycle — the human should never have to remind you to circle back.',
+].join('\n')
+
+const CYCLE = CHAT_CHARTER + '\n\nRun one OpenVisio autonomy cycle: call poll_inbox and handle mentions + follow-ups. Reply in 1-3 sentences, @mention people by their EXACT full name, at most one reply per channel. Then stop.'
+const CYCLE_FAST = CHAT_CHARTER + '\n\nNew chat activity. If a specific mention is given above, post that reply FIRST with mcp__openvisio-team__post_message. Then call poll_inbox and handle any .followUps (thread replies you are part of, even without an @mention) — ignore .tasks/.claimable. Post AT MOST ONE reply per channel: if the same person sent several nudges, answer them together in ONE post. If asked for work you have no tool for, say so plainly and offer to file a ticket. Never invent progress. Reply in 1-3 sentences, no summary. Then stop.'
+
+// ── CODE agents (--workdir given): full file + Bash + git/gh surface. ─────────
+// A stable "who you are / how you work" charter prepended to every code cycle.
+const CODE_CHARTER = [
+  'YOU ARE a connected CODING agent in an OpenVisio team, running ON THE USER\'S LAPTOP. You have REAL tools — use them; do NOT claim you lack a capability without checking what you actually hold. Your toolbox:',
+  '  • openvisio-team chat/ticket tools (mcp__openvisio-team__*) — read mentions, post messages, comment on tickets, react.',
+  '  • Read / Grep / Glob / Edit / Write / MultiEdit — inspect AND change code.',
+  '  • Bash — git (branch, commit, push a branch), gh (clone repos, open PRs), run tests/builds.',
+  'YOUR WORKSPACE: your working directory is a WORKSPACE ROOT that holds the org\'s repos as subfolders. You are NOT limited to one repo — you work across ALL of them from here. For any task: find the relevant repo under the workspace; if it isn\'t cloned yet, CLONE it (gh repo clone <org>/<repo>, or git clone <url>) and then work inside that subfolder. Never make the user tell you a path or clone things for you.',
+  'CAPABILITY CHECK: before you EVER answer "I can\'t do that", verify against the tools above. If a tool exists for it, DO it. To be explicit: you CAN read/inspect any of the org\'s codebases, clone a repo you don\'t have yet, work on it, create a branch, and raise a PR — say YES to these and then actually do them.',
+  '',
+  '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.',
+  '  2. FINISH, then REPORT. Your LAST action every cycle is a status back to the requester: comment_ticket with what you did (branch + PR link + test result) AND a short channel reply that @mentions the person who asked, by their EXACT full name (a mention only links on an exact full-name match).',
+  '  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 reply per channel per cycle; answer several nudges together.',
+].join('\n')
+
+const CODE_FULL = CODE_CHARTER + '\n\n' + [
+  'THIS CYCLE: call get_marching_orders and poll_inbox to see assigned tickets + mentions, then act on them.',
+  'For real code work (an assigned ticket, or a mention asking for changes), run the full flow end-to-end:',
+  '  1. GET THE CODE: locate the target repo under your workspace root. If it\'s already a subfolder, cd in and `git pull`; if it isn\'t cloned yet, clone it into the workspace (gh repo clone <org>/<repo>, or git clone <url>) and cd in. Do this yourself — never ask the user for a path.',
+  '  2. BRANCH: git checkout -B agent/<short-task-slug>. NEVER work on, commit to, or push main/master.',
+  '  3. CHANGE + VERIFY: Read/Edit/Write the files; run the tests or build if the repo has them.',
+  '  4. COMMIT + PUSH YOUR BRANCH: git add -A && git commit -m "…"; then git push -u origin agent/<slug>. Only ever push your own agent/* branch. Never --force, never push to main/master, never merge.',
+  '  5. RAISE A PR: gh pr create --fill --base <default-branch> --head agent/<slug> (a clear title + a body summarizing the change and how you verified it). Never gh pr merge.',
+  '  6. CLOSE THE LOOP: comment_ticket with the summary + PR link/branch, and post a channel reply that @mentions the requester by their exact full name.',
+  'Bash is for git / gh / tests / clone ONLY — never to hunt for credentials (they are given to you above).',
+].join('\n')
+
+const CODE_FAST = CODE_CHARTER + '\n\n' + [
+  'New chat activity. If a specific mention is given above, post that reply FIRST with mcp__openvisio-team__post_message — before any Bash.',
+  'Then poll_inbox and handle .followUps (thread replies you are part of, even without an @mention), at most one reply per channel.',
+  'If a message asks for real CODE work, do the WHOLE job now — branch (checkout -B agent/<slug>), edit, run tests, commit, push your branch, open a PR (gh pr create), then reply with the PR link and @mention the requester by exact full name. Never push to main, never --force, never merge.',
+  'Do NOT promise and stop — finish and report in THIS cycle. Reply 1-3 sentences, no summary. Then stop.',
+].join('\n')
+
+// Bash covers git/gh/clone/tests; the deny list is where the guardrails live.
 const CODE_TOOLS = ['Read', 'Grep', 'Glob', 'Edit', 'Write', 'MultiEdit', 'TodoWrite', 'Bash', 'mcp__openvisio-team__*']
-const DENY_TOOLS = ['Bash(git push:*)', 'Bash(git reset --hard:*)', 'Bash(git clean:*)', 'Bash(rm:*)', 'Bash(sudo:*)', 'Bash(chmod:*)', 'Bash(curl:*)', 'Bash(wget:*)', 'Bash(npm publish:*)', 'Bash(pnpm publish:*)', 'Bash(gh pr merge:*)', 'Bash(gh repo:*)']
+// Push + PR creation ARE allowed (agents raise PRs), but main/master, force-pushes,
+// merges and destructive/publishing/repo-deleting commands stay blocked.
+const DENY_TOOLS = [
+  'Bash(git push --force:*)', 'Bash(git push -f:*)', 'Bash(git push --force-with-lease:*)',
+  'Bash(git push origin main:*)', 'Bash(git push origin master:*)',
+  'Bash(git push origin HEAD:main:*)', 'Bash(git push origin HEAD:master:*)',
+  'Bash(git reset --hard:*)', 'Bash(git clean:*)',
+  'Bash(rm:*)', 'Bash(sudo:*)', 'Bash(chmod:*)', 'Bash(curl:*)', 'Bash(wget:*)',
+  'Bash(npm publish:*)', 'Bash(pnpm publish:*)',
+  'Bash(gh pr merge:*)', 'Bash(gh repo delete:*)',
+]
 
 const FAST = 2500
 const SLOW = 6000
@@ -29,15 +86,29 @@ const MAX_TURNS = 15
 const SESSION_IDLE_MS = 1200000
 // A single cycle must finish within this or it's abandoned — otherwise a hung
 // cycle (e.g. an MCP tool stalling on a down bridge) would leave `busy` stuck
-// true forever and silently queue every later mention.
+// true forever and silently queue every later mention. Code cycles get a much
+// longer budget: a real clone → branch → test → push → PR flow legitimately takes
+// minutes, and cutting it off mid-job is itself a "never circled back" failure.
 const MAX_CYCLE_MS = 240000
+const MAX_CODE_CYCLE_MS = 900000
 
 export async function runWatch({ flags }) {
   const slug = flags.name ? slugify(String(flags.name)) : null
   const saved = slug ? readConfig(slug) : null
   const claude = String(flags.claude || onPath('claude') || 'claude')
   const mcpConfig = String(flags['mcp-config'] || (saved && saved.mcpConfig) || '')
-  const workdir = flags.workdir === true ? process.cwd() : (flags.workdir ? String(flags.workdir) : '')
+  // Code mode is the DEFAULT: an agent lives on the user's laptop and should just be
+  // able to work across the org's repos with no per-repo setup. So `workdir` resolves
+  // to (in order) an explicit --workdir/--workspace, the saved workspace, or the
+  // shared DEFAULT_WORKSPACE — always non-empty unless the agent is opted into
+  // --chat-only. It's a WORKSPACE ROOT (holds repos as subfolders + clones missing
+  // ones), not a single repo. Created on demand so the Claude session can cwd into it.
+  const chatOnly = !!flags['chat-only'] || (saved && saved.chatOnly === true)
+  const explicitWorkdir = flags.workdir === true ? process.cwd()
+    : flags.workdir ? String(flags.workdir)
+    : flags.workspace ? String(flags.workspace) : ''
+  const workdir = chatOnly ? '' : (explicitWorkdir || (saved && (saved.workspace || saved.workdir)) || DEFAULT_WORKSPACE)
+  if (workdir) { try { mkdirSync(workdir, { recursive: true }) } catch { /* best-effort; spawn will surface a real problem */ } }
 
   // Backend agents (connect --backend) drive autonomy over a real-time WS instead
   // of REST-polling the frontend relay. Detected by the saved mode / a --ws flag.
@@ -67,6 +138,7 @@ export async function runWatch({ flags }) {
 // after MAX_TURNS or SESSION_IDLE_MS. Returns { runCycle, canCode }.
 function createCycleRunner({ claude, mcpConfig, workdir, log, debug }) {
   const canCode = !!workdir
+  const maxCycleMs = canCode ? MAX_CODE_CYCLE_MS : MAX_CYCLE_MS
   let child = null
   let turnsThisSession = 0
   let sessionStartedAt = 0
@@ -114,7 +186,9 @@ function createCycleRunner({ claude, mcpConfig, workdir, log, debug }) {
     })
     c.on('exit', (code) => { if (c !== child) { log('old session exited ' + code); return } log('session exited ' + code); child = null; settleTurn({ type: 'result', subtype: 'exit' }) })
     c.on('error', () => { if (c !== child) return; child = null; settleTurn({ type: 'result', subtype: 'error' }) })
-    log('warm session started')
+    log('warm session started' + (canCode
+      ? ' [CODE mode — workspace ' + workdir + ' — finds/clones the org\'s repos here, branches, pushes, opens PRs]'
+      : ' [CHAT-ONLY mode (--chat-only) — chat/ticket tools only, no code work]'))
   }
 
   function runCycle(prompt) {
@@ -131,11 +205,11 @@ function createCycleRunner({ claude, mcpConfig, workdir, log, debug }) {
       // and queued mentions can proceed.
       clearCycleTimer()
       cycleTimer = setTimeout(() => {
-        log('cycle TIMED OUT after ' + Math.round(MAX_CYCLE_MS / 1000) + 's — killing the session so the queue can proceed')
+        log('cycle TIMED OUT after ' + Math.round(maxCycleMs / 1000) + 's — killing the session so the queue can proceed')
         try { child && child.kill() } catch { /* already gone */ }
         child = null
         settleTurn({ type: 'result', subtype: 'timeout' })
-      }, MAX_CYCLE_MS)
+      }, maxCycleMs)
       try { child.stdin.write(JSON.stringify({ type: 'user', message: { role: 'user', content: prompt } }) + '\n') }
       catch { settleTurn({ type: 'result', subtype: 'write-failed' }) }
     })
@@ -167,7 +241,7 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir,
   // The Mastra bridge authenticates per-CALL, not per-connection: every
   // openvisio-team tool needs agent_identifier + agent_api_key as arguments.
   // Hand them to the model up front so it never shells around hunting for them.
-  const credNote = `AUTH: the openvisio-team (mcp__openvisio-team__*) tools REQUIRE two arguments on EVERY call — agent_identifier: "${identifier}" and agent_api_key: "${apiKey}". Include BOTH on every openvisio-team tool call (post_message, poll_inbox, react_message, comment_ticket, …). They are given to you right here: do NOT search for them, do NOT run Bash/shell/grep/cat/find, do NOT read memory — just call the tools with these exact values.`
+  const credNote = `AUTH: the openvisio-team (mcp__openvisio-team__*) tools REQUIRE two arguments on EVERY call — agent_identifier: "${identifier}" and agent_api_key: "${apiKey}". Include BOTH on every openvisio-team tool call (post_message, poll_inbox, react_message, comment_ticket, …). They are given to you right here — do NOT hunt for them (no Bash/grep/cat/find to locate credentials, no reading memory); just call the tools with these exact values. (Bash/git/gh ARE for your code work — this rule is only about not searching for these keys.)`
 
   async function drain(kind, context) {
     if (context) pending.push(context)