openvisio-agent 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.8.0",
+  "version": "0.9.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/watch.mjs

@@ -34,16 +34,19 @@ const REPLY_DISCIPLINE = [
 
 // ── 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.',
+  'YOU ARE a connected agent in an OpenVisio team, running in CHAT-ONLY mode. Your tools are the openvisio-team chat/ticket tools — post_message, poll_inbox, comment_ticket, react_message (your runtime may namespace them, e.g. mcp__openvisio-team__post_message or openvisio-team_post_message — call whatever names appear in your tool list). 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.',
   '',
   REPLY_DISCIPLINE,
 ].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\n' + [
+// NOTE: the CHARTER (who you are + reply discipline) is NOT prepended here — it is
+// passed ONCE as the session's system prompt (cacheable, not re-billed every cycle).
+// These bases are the small per-cycle instructions only. See createCycleRunner.
+const CYCLE = 'Run 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 = [
   'New chat activity. Do EXACTLY ONE of these:',
-  '  • IF a specific mention/message FOR YOU is given above: reply to THAT ONE message exactly once with mcp__openvisio-team__post_message, then STOP. Do NOT call poll_inbox and do NOT answer anything else this cycle — you already have the message; polling would make you re-answer it and double-post.',
+  '  • IF a specific mention/message FOR YOU is given above: reply to THAT ONE message exactly once with post_message, then STOP. Do NOT call poll_inbox and do NOT answer anything else this cycle — you already have the message; polling would make you re-answer it and double-post.',
   '  • IF NO specific mention is given above: call poll_inbox and reply only to items truly directed at YOU (a question to you, or a reply to your own message) — SKIP chatter aimed at someone else / another agent, ignore .tasks/.claimable, at most one reply per channel.',
   'Post ONE message total for the thing you are answering — compose it fully, then send once. Never send a reply and then a "better" version; never repeat a reply you already sent. Be sure of your answer before sending. If asked for work you have no tool for, say so plainly and offer to file a ticket. 1-3 sentences, no summary. Then stop.',
 ].join('\n')
@@ -52,7 +55,7 @@ const CYCLE_FAST = CHAT_CHARTER + '\n\n' + [
 // 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.',
+  '  • openvisio-team chat/ticket tools — read mentions, post messages, comment on tickets, react (post_message / poll_inbox / comment_ticket / react_message; your runtime may namespace them — use whatever names appear in your tool list).',
   '  • 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.',
@@ -67,7 +70,7 @@ const CODE_CHARTER = [
   REPLY_DISCIPLINE,
 ].join('\n')
 
-const CODE_FULL = CODE_CHARTER + '\n\n' + [
+const CODE_FULL = [
   'THIS CYCLE: call get_marching_orders and poll_inbox to see assigned tickets + mentions, then act on them.',
   'ACKNOWLEDGE ONCE: for a task assigned to you that you have NOT already acknowledged, post a SINGLE one-line comment_ticket ("On it — picking this up now") before you start. First check the ticket/thread — if you already acknowledged it on an earlier cycle, skip this and just keep working. Then report only when you have the result.',
   'For real code work (an assigned ticket, or a mention asking for changes), run the full flow end-to-end:',
@@ -80,9 +83,9 @@ const CODE_FULL = CODE_CHARTER + '\n\n' + [
   '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' + [
+const CODE_FAST = [
   'New chat activity. Do EXACTLY ONE of these:',
-  '  • IF a specific mention/message FOR YOU is given above: reply to THAT ONE message exactly once with mcp__openvisio-team__post_message, then STOP. Do NOT call poll_inbox and do NOT answer anything else this cycle — polling would re-surface the same message and make you double-post.',
+  '  • IF a specific mention/message FOR YOU is given above: reply to THAT ONE message exactly once with post_message, then STOP. Do NOT call poll_inbox and do NOT answer anything else this cycle — polling would re-surface the same message and make you double-post.',
   '  • IF NO specific mention is given above: call poll_inbox and reply only to items directed at YOU (asks you something, or responds to your own message) — SKIP chatter aimed at someone else / another agent; at most one reply per channel.',
   'If the message asks YOU 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 once with the PR link and @mention the requester by exact full name. Never push to main, never --force, never merge.',
   'Post ONE message for the thing you are answering — send it once; never a reply then a "better" version; never repeat a reply you already sent; be sure before you send. Do NOT promise and stop — finish and report in THIS cycle. 1-3 sentences, no summary. Then stop.',
@@ -122,7 +125,12 @@ const DENY_TOOLS = [
 const FAST = 2500
 const SLOW = 6000
 const IDLE_AFTER = 60000
-const MAX_TURNS = 15
+// Recycle the warm session after ONE cycle. Autonomy cycles are independent (a
+// mention → a reply, a task → its work), so keeping a session across cycles just
+// re-bills the entire prior history on every new cycle — the #1 token sink. Fresh
+// per cycle keeps each cycle's cost to its own work (the static charter/creds ride
+// in the cached system prompt, so a fresh spawn is cheap).
+const MAX_TURNS = 1
 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
@@ -227,7 +235,7 @@ export async function runWatch({ flags }) {
 // The openvisio-team MCP is declared in an `opencode.json` written into the run cwd
 // (opencode reads it from there). `--auto` approves tool use non-interactively.
 // Same { runCycle, canCode } contract as the Claude runner.
-function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, maxCycleMs, log, debug, model }) {
+function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, maxCycleMs, log, debug, model, systemPrompt }) {
   // opencode reads opencode.json from its CWD: the code workspace, or a dedicated
   // per-agent dir for chat-only agents.
   const cwd = workdir || join(OV_DIR, 'opencode-' + (cfgKey || 'agent'))
@@ -253,7 +261,10 @@ function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, ma
     return new Promise((resolve) => {
       ensureConfig()
       const m = cycleModel || model
-      const args = ['run', prompt, '--auto', ...(m ? ['--model', m] : [])]
+      // opencode has no system-prompt flag; each run is a fresh process, so fold the
+      // charter/creds into the message (still not re-accumulated across cycles).
+      const full = systemPrompt ? systemPrompt + '\n\n' + prompt : prompt
+      const args = ['run', full, '--auto', ...(m ? ['--model', m] : [])]
       let child = null, done = false
       const finish = (o) => { if (done) return; done = true; clearTimeout(timer); resolve(o) }
       const timer = setTimeout(() => {
@@ -276,12 +287,12 @@ function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, ma
 // ── Claude Code warm-session cycle runner (shared by the REST + WS loops) ─────
 // One persistent stream-json session, poked with a prompt per cycle. Recycled
 // after MAX_TURNS or SESSION_IDLE_MS. Returns { runCycle, canCode }.
-function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfig, workdir, log, debug, model, onTool }) {
+function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfig, workdir, log, debug, model, onTool, systemPrompt }) {
   const canCode = !!workdir
   const maxCycleMs = canCode ? MAX_CODE_CYCLE_MS : MAX_CYCLE_MS
   // opencode drives cycles differently — a headless `opencode run` per cycle rather
   // than a persistent stream-json session. Same { runCycle, canCode } contract.
-  if (agent === 'opencode') return createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, maxCycleMs, log, debug, model })
+  if (agent === 'opencode') return createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, maxCycleMs, log, debug, model, systemPrompt })
   let child = null
   // The model the CURRENT session was spawned with. runCycle can pass a different
   // model per cycle (cheap for chat, stronger for code) — a change recycles the
@@ -312,7 +323,9 @@ function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfi
   function ensureSession() {
     if (child && !child.killed) return
     if (!mcpConfig) { log('WARNING: no MCP config — the agent can react to events but has no tools to act. Re-connect with --mcp-url.') }
-    const base = ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose', '--strict-mcp-config', '--mcp-config', mcpConfig, ...(sessionModel ? ['--model', sessionModel] : [])]
+    // The charter + creds ride in the system prompt (cacheable → not re-billed each
+    // cycle), leaving only the small per-cycle instruction in the user message.
+    const base = ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose', '--strict-mcp-config', '--mcp-config', mcpConfig, ...(sessionModel ? ['--model', sessionModel] : []), ...(systemPrompt ? ['--append-system-prompt', systemPrompt] : [])]
     const args = canCode ? [...base, '--allowedTools', ...CODE_TOOLS, '--disallowedTools', ...DENY_TOOLS] : [...base, '--allowedTools', 'mcp__openvisio-team__*']
     const c = spawn(claude, args, { cwd: workdir || undefined, stdio: ['pipe', 'pipe', 'inherit'] })
     child = c
@@ -387,9 +400,16 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
   // agent:status broadcast (thinking → working → typing → done).
   const statusTargets = new Set()
   const emitStatus = (state) => { for (const c of statusTargets) { try { handle && handle.sendStatus(c, state) } catch { /* best-effort */ } } }
-  const { runCycle, canCode } = createCycleRunner({
+  const canCode = !!workdir
+  // The Mastra bridge authenticates per-CALL: every openvisio-team tool needs
+  // agent_identifier + agent_api_key as arguments. Hand them over up front.
+  const credNote = `AUTH: the 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, get_marching_orders, …). These tools may appear in your tool list namespaced (mcp__openvisio-team__post_message on Claude Code, openvisio-team_post_message on opencode) — call whichever names you actually see. The credentials are given to you right here — do NOT hunt for them (no Bash/grep/cat/find, 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.)`
+  // The STATIC charter + creds are the session system prompt (cached, billed once),
+  // NOT re-sent in every cycle's user message — the big token saving.
+  const systemPrompt = (canCode ? CODE_CHARTER : CHAT_CHARTER) + '\n\n' + credNote
+  const { runCycle } = createCycleRunner({
     claude, agent, mcpUrl, mcpHeaders: { 'x-agent-api-key': apiKey, 'x-agent-identifier': identifier },
-    cfgKey: identifier, mcpConfig, workdir, log, debug, model,
+    cfgKey: identifier, mcpConfig, workdir, log, debug, model, systemPrompt,
     // The moment the agent calls post_message it is about to speak → "typing".
     onTool: (name) => { if (/post_message/.test(name)) emitStatus('typing') },
   })
@@ -417,11 +437,6 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
   // events and drained into the next cycle's prompt.
   const pending = []
 
-  // 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 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.)`
-
   // Higher rank wins when coalescing cycles requested while one is running.
   const RANK = { fast: 0, intro: 1, sweep: 2, full: 3 }
   const baseFor = (kind) => kind === 'intro' ? INTRO : (kind === 'full' || kind === 'sweep') ? fullPrompt : fastPrompt
@@ -431,7 +446,9 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
     if (busy) { queued = (RANK[kind] ?? 0) >= (RANK[queued] ?? 0) ? kind : queued; log('busy — queued a ' + kind + ' follow-up cycle'); return }
     busy = true
     const ctx = pending.splice(0) // take everything accumulated so far
-    const prompt = credNote + '\n\n' + (ctx.length ? ctx.join('\n') + '\n\n' : '') + baseFor(kind)
+    // credNote + charter live in the cached system prompt now — the per-cycle
+    // message is just the event context + the small base instruction.
+    const prompt = (ctx.length ? ctx.join('\n') + '\n\n' : '') + baseFor(kind)
     // Chat-shaped cycles (mentions/intro) may run on the cheaper chat model; code
     // work (full/sweep) uses the main model.
     const useModel = (kind === 'fast' || kind === 'intro') ? liteModel : codeModel
@@ -552,7 +569,7 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
       // takes it to working → typing → done).
       if (cid != null) { statusTargets.add(cid); try { handle && handle.sendStatus(cid, 'thinking') } catch { /* best-effort */ } }
       const ctx = cid != null
-        ? `You were @mentioned in OpenVisio channel ${cid}${who ? ` by "${who}"` : ''}: "${text}". This mention is FOR YOU. Send EXACTLY ONE reply with mcp__openvisio-team__post_message — arguments: channel_id ${cid}${threadRoot != null ? `, parent_id ${threadRoot} (reply IN THAT THREAD, do not start a new top-level message)` : ''}, plus agent_identifier + agent_api_key from the AUTH line above, and a 1-3 sentence reply. Compose the whole answer, then post it ONCE — do NOT post a first reply and then a revised/"better" one. FIRST read the recent messages in this thread: if you already answered this, or another agent was the one addressed, do NOT post at all. Be sure of your answer before sending.${who ? ` To @mention them back, write their EXACT full name "@${who}" (a mention only links when the name matches exactly — "@${who.split(' ')[0]}" alone will NOT).` : ''} You ALREADY have the message here — do NOT poll_inbox, and after your single reply, STOP.`
+        ? `You were @mentioned in OpenVisio channel ${cid}${who ? ` by "${who}"` : ''}: "${text}". This mention is FOR YOU. Send EXACTLY ONE reply with post_message — arguments: channel_id ${cid}${threadRoot != null ? `, parent_id ${threadRoot} (reply IN THAT THREAD, do not start a new top-level message)` : ''}, plus agent_identifier + agent_api_key from the AUTH line above, and a 1-3 sentence reply. Compose the whole answer, then post it ONCE — do NOT post a first reply and then a revised/"better" one. FIRST read the recent messages in this thread: if you already answered this, or another agent was the one addressed, do NOT post at all. Be sure of your answer before sending.${who ? ` To @mention them back, write their EXACT full name "@${who}" (a mention only links when the name matches exactly — "@${who.split(' ')[0]}" alone will NOT).` : ''} You ALREADY have the message here — do NOT poll_inbox, and after your single reply, STOP.`
         : undefined
       void drain('fast', ctx)
     } else if (k === 'error') {
@@ -609,7 +626,11 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
 function loop({ host, key, slug, claude, agent, mcpConfig, mcpUrl, workdir, model, chatModel, debug }) {
   const log = (m) => process.stdout.write('[warm ' + new Date().toISOString() + '] ' + m + '\n')
   const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
-  const { runCycle, canCode } = createCycleRunner({ claude, agent, mcpUrl, mcpHeaders: { Authorization: 'Bearer ' + key }, cfgKey: slug, mcpConfig, workdir, log, debug, model })
+  const canCode = !!workdir
+  // Static charter as the cached system prompt (this loop's MCP authenticates via a
+  // Bearer header, so no per-call creds are needed in the prompt).
+  const systemPrompt = canCode ? CODE_CHARTER : CHAT_CHARTER
+  const { runCycle } = createCycleRunner({ claude, agent, mcpUrl, mcpHeaders: { Authorization: 'Bearer ' + key }, cfgKey: slug, mcpConfig, workdir, log, debug, model, systemPrompt })
   const fullPrompt = canCode ? CODE_FULL : CYCLE
   const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
   const liteModel = chatModel || model // cheaper model for chat/quick cycles