@doguyilmaz/konvoy 0.2.0 → 0.3.1

package/README.md

@@ -40,6 +40,7 @@ to download; the npm package is a few kilobytes of source and runs on the Bun yo
 ## Use
 
 ```bash
+konvoy                         # start: resume this directory's session or create one, then talk
 konvoy new "refactor the auth layer"
 konvoy new                     # no goal: named after the directory, like sinkaf-8f3a
 konvoy send codex "start with the token refresh path"
@@ -58,6 +59,20 @@ konvoy version
 konvoy dashboard --port 4000  # local page with the same numbers as `usage --chart`
 ```
 
+Bare `konvoy` is the everyday entry: it resumes the session bound to this directory or creates
+one named after it, then reads what you type. Plain text is a turn against the current agent; a
+line starting with `/` runs any command from the list (`/usage --all`, `/rename token-refresh`,
+`/attach`), plus `/use <agent>`, `/goal <text>`, `/help` and `/quit`. Ctrl-D leaves, Ctrl-C stops a
+running turn and leaves, and piped stdin runs one turn per line.
+
+```text
+sinkaf-8f3a claude> fix the token refresh
+  · Read src/auth.ts
+Switched the refresh to fire on 401 with a single in-flight retry.
+sinkaf-8f3a claude> /use codex
+sinkaf-8f3a codex> review that diff
+```
+
 ## Sample output
 
 Captured by running konvoy against a scratch database, not copied from a real project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doguyilmaz/konvoy",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "One session across Claude Code, Codex, Kiro CLI and opencode: bind, hand off, fail over.",
   "license": "MIT",
   "type": "module",

package/src/args.ts

@@ -5,7 +5,7 @@ export interface Args {
 
 // Flags that are switches, so `konvoy rm --yes <slug>` keeps its slug. Their consumers are the
 // `=== true` checks in cli.ts; a value flag (--session, --port) is anything not listed here.
-const SWITCHES = new Set(['all', 'yes', 'global', 'chart', 'help'])
+const SWITCHES = new Set(['all', 'yes', 'global', 'chart', 'help', 'h', 'version', 'v', 'V'])
 
 export function parseArgs(argv: string[]): Args {
   const positional: string[] = []

package/src/cli.ts

@@ -22,6 +22,7 @@ import { cmdRename } from './commands/rename'
 import { cmdUsage } from './commands/usage'
 import { cmdDashboard } from './commands/dashboard'
 import { formatCommandList, resolveCommandName, type CommandName } from './commands/table'
+import { runRepl, startSession, type ReplIo } from './commands/repl'
 import type { AgentId } from './types'
 import pkg from '../package.json'
 
@@ -29,10 +30,12 @@ const VERSION = pkg.version
 
 export const USAGE = `konvoy ${VERSION}
 
+  konvoy                                   start: resume this directory's session or create one, then talk
+
 ${formatCommandList()}
 
 agents: ${agentIds.join(', ')}
-flags:  --session <slug>
+flags:  --session <slug>, --version (-v), --help (-h)
 `
 
 interface CommandContext {
@@ -112,20 +115,39 @@ const handlers: Record<CommandName, Handler> = {
     }),
 }
 
-export async function main(argv: string[]): Promise<number> {
+const stdio = (): ReplIo => ({
+  lines: console as unknown as AsyncIterable<string>,
+  write: (text) => {
+    process.stdout.write(text)
+  },
+  tty: Boolean(process.stdin.isTTY),
+})
+
+export async function main(argv: string[], io: ReplIo = stdio()): Promise<number> {
   const args = parseArgs(argv)
   const [command, ...rest] = args._
   const cwd = process.cwd()
   const slug = typeof args.flags.session === 'string' ? args.flags.session : undefined
 
-  if (!command || command === 'help' || args.flags.help) {
+  if (args.flags.version === true || args.flags.v === true || args.flags.V === true) {
+    console.log(`konvoy ${VERSION}`)
+    return 0
+  }
+  if (command === 'help' || args.flags.help === true || args.flags.h === true) {
     console.log(USAGE)
-    // asking for help is not a usage error; running konvoy with nothing is
-    return command || args.flags.help ? 0 : 1
+    return 0
+  }
+  if (!command) {
+    const stray = Object.keys(args.flags).filter((f) => f !== 'session')
+    if (stray.length > 0) {
+      console.error(`unknown flag ${stray[0]!.length === 1 ? '-' : '--'}${stray[0]}`)
+      console.log(USAGE)
+      return 2
+    }
   }
 
   try {
-    return await dispatch(command, rest, cwd, slug, args)
+    return command ? await dispatch(command, rest, cwd, slug, args) : await interactive(io, cwd, slug)
   } catch (error) {
     if (Bun.env.KONVOY_DEBUG === '1') throw error
     console.error(`konvoy: ${error instanceof Error ? error.message : String(error)}`)
@@ -150,6 +172,26 @@ async function dispatch(command: string, rest: string[], cwd: string, slug: stri
   return handlers[name]({ db, cfg, cwd, args, slug }, rest)
 }
 
+async function interactive(io: ReplIo, cwd: string, slug: string | undefined): Promise<number> {
+  const db = openDb(dbPath())
+  const cfg = await loadConfig({ cwd: (slug ? getSessionBySlug(db, slug)?.cwd : undefined) ?? cwd })
+  const session = await startSession(db, cfg, cwd, slug)
+  if (!session) {
+    console.error(slug ? `no konvoy session named "${slug}"` : 'could not create a session here')
+    return 2
+  }
+  return runRepl(io, db, cfg, cwd, session, (tokens, current) => {
+    const a = parseArgs(tokens)
+    const [cmd = '', ...r] = a._
+    const name = resolveCommandName(cmd)
+    if (!name) {
+      console.error(`unknown command "/${cmd}" - /help lists them`)
+      return 2
+    }
+    return handlers[name]({ db, cfg, cwd, args: a, slug: current }, r)
+  })
+}
+
 if (import.meta.main) {
   process.exitCode = await main(Bun.argv.slice(2))
 }

package/src/commands/repl.ts

@@ -0,0 +1,125 @@
+import type { Database } from 'bun:sqlite'
+import type { Config } from '../config/schema'
+import type { AgentId, Session } from '../types'
+import { agentIds } from '../adapters'
+import { resolveAgent } from '../config/load'
+import { sessionDir } from '../paths'
+import { currentSession, getSessionBySlug, lastTurnAgent, listSessions, setGoal } from '../store/queries'
+import { cmdNew } from './new'
+import { formatCommandList } from './table'
+
+export interface ReplIo {
+  lines: AsyncIterable<string>
+  write: (text: string) => void
+  tty: boolean
+}
+
+/** runs one command line through the command table, as `konvoy <tokens>` would, for the given session */
+export type Run = (tokens: string[], slug: string) => Promise<number> | number
+
+const INNER = `  /use <agent>                             talk to this agent from now on
+  /goal <text>                             set the session goal
+  /help                                    this list
+  /quit                                    leave (Ctrl-D does too)
+`
+
+export const replHelp = (): string => INNER + formatCommandList().replaceAll('  konvoy ', '  /') + '\n'
+
+export async function startSession(db: Database, cfg: Config, cwd: string, slug?: string): Promise<Session | null> {
+  if (slug) return getSessionBySlug(db, slug)
+  const current = currentSession(db, cwd)
+  if (current) return current
+  if ((await cmdNew(db, cfg, cwd, '')) !== 0) return null
+  return currentSession(db, cwd)
+}
+
+export async function runRepl(
+  io: ReplIo,
+  db: Database,
+  cfg: Config,
+  cwd: string,
+  start: Session,
+  run: Run,
+): Promise<number> {
+  let session = start
+  let agent: AgentId = session.lead
+  const prompt = (): void => {
+    if (io.tty) io.write(`${session.slug} ${agent}> `)
+  }
+  const refresh = (): boolean => {
+    const fresh = listSessions(db).find((s) => s.id === session.id)
+    if (fresh) session = fresh
+    return fresh !== undefined
+  }
+
+  prompt()
+  for await (const raw of io.lines) {
+    const line = raw.trim()
+    if (line === '') {
+      prompt()
+      continue
+    }
+    if (!line.startsWith('/')) {
+      await run(['send', agent, line], session.slug)
+      // failover never falls back, so the agent that answered is the one to keep talking to
+      const moved = lastTurnAgent(db, session.id)
+      if (moved && moved !== agent) agent = moved
+      prompt()
+      continue
+    }
+
+    const [cmd = '', ...rest] = line.slice(1).split(/\s+/)
+    if (cmd === 'quit' || cmd === 'exit' || cmd === 'q') break
+    if (cmd === 'help') {
+      io.write(replHelp())
+    } else if (cmd === 'use') {
+      const next = rest[0] ?? ''
+      if (!agentIds.includes(next as AgentId)) {
+        console.error(`unknown agent "${next}" - expected one of ${agentIds.join(', ')}`)
+      } else if (!resolveAgent(cfg, next as AgentId).enabled) {
+        console.error(`${next} is disabled in this konvoy config`)
+      } else {
+        agent = next as AgentId
+      }
+    } else if (cmd === 'goal') {
+      const goal = rest.join(' ')
+      if (!goal) {
+        console.error('usage: /goal <text>')
+      } else {
+        setGoal(db, session.id, goal)
+        const context = Bun.file(`${sessionDir(session.cwd, session.slug)}/CONTEXT.md`)
+        if (await context.exists()) await Bun.write(context, `${await context.text()}\n## Goal\n\n${goal}\n`)
+        refresh()
+      }
+    } else if (cmd === 'rename') {
+      if (rest.length === 0) console.error('usage: /rename <new-name>')
+      else {
+        await run(['rename', session.slug, rest.join(' ')], session.slug)
+        refresh()
+      }
+    } else if (cmd === 'attach') {
+      await run(['attach', rest[0] ?? agent, ...rest.slice(1)], session.slug)
+    } else {
+      await run([cmd, ...rest], session.slug)
+      if (cmd === 'resume' && rest[0]) {
+        const target = getSessionBySlug(db, rest[0])
+        if (target) {
+          session = target
+          agent = target.lead
+        }
+      } else if (cmd === 'new') {
+        const created = currentSession(db, cwd)
+        if (created) {
+          session = created
+          agent = created.lead
+        }
+      } else if (!refresh()) {
+        console.error(`session ${session.slug} is gone`)
+        return 0
+      }
+    }
+    prompt()
+  }
+  if (io.tty) io.write('\n')
+  return 0
+}

package/src/commands/roster.ts

@@ -28,7 +28,7 @@ export function cmdRoster(db: Database, cfg: Config, cwd: string, slug?: string)
     }
   })
 
-  console.log(`session ${session.slug} - ${session.goal}`)
+  console.log(session.goal ? `session ${session.slug} - ${session.goal}` : `session ${session.slug}`)
   console.log(formatRoster(rows))
   for (const model of duplicateModels(rows)) {
     console.log(`warning: ${model} is used by more than one agent - a second opinion from the same model is not one`)

package/src/store/queries.ts

@@ -76,6 +76,10 @@ export function touchSession(db: Database, id: string): void {
   ).run({ id, now: now() })
 }
 
+export function setGoal(db: Database, id: string, goal: string): void {
+  db.query('UPDATE session SET goal = $goal WHERE id = $id').run({ goal, id })
+}
+
 export function renameSession(db: Database, id: string, slug: string): void {
   db.query('UPDATE session SET slug = $slug WHERE id = $id').run({ slug, id })
 }