@doguyilmaz/konvoy 0.1.2 → 0.3.0

package/README.md

@@ -40,7 +40,9 @@ 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"
 konvoy ls
 konvoy resume                  # make a session current again and show its roster
@@ -52,10 +54,25 @@ konvoy attach kiro --id cli_8a1…   # adopt a session you started in kiro's own
 konvoy doctor
 konvoy update --all    # every agent CLI; konvoy itself follows its install channel (see Install)
 konvoy rm stale-slug --yes
+konvoy rename stale-slug token-refresh   # the session's .konvoy folder follows
 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.
@@ -164,6 +181,9 @@ Global `~/.config/konvoy/config.jsonc`, per project `.konvoy/config.jsonc`. The
 file wins. `konvoy config get` shows each agent's resolved settings and whether a value came
 from that agent, from `defaults`, or from konvoy's own built-in.
 
+`konvoy new` also writes `.konvoy/.gitignore` (`*`, then `!config.jsonc`), so a session's `CONTEXT.md`
+and `LEDGER.md` never reach git while the project config can be committed.
+
 ```jsonc
 {
   "defaults": { "effort": "high", "permission": "edit" },

package/package.json

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

package/src/cli.ts

@@ -18,9 +18,11 @@ import { cmdUpdate } from './commands/update'
 import { cmdConfig } from './commands/config'
 import { cmdResume } from './commands/resume'
 import { cmdRm } from './commands/rm'
+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'
 
@@ -28,6 +30,8 @@ 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(', ')}
@@ -78,6 +82,14 @@ const handlers: Record<CommandName, Handler> = {
     const [action, key, value] = rest
     return cmdConfig(ctx.cfg, ctx.cwd, action ?? 'get', key, value, { global: ctx.args.flags.global === true })
   },
+  rename: (ctx, rest) => {
+    const [from, to] = rest
+    if (!from || !to) {
+      console.error('usage: konvoy rename <session> <new-name>')
+      return 2
+    }
+    return cmdRename(ctx.db, from, to)
+  },
   rm: (ctx, rest) => {
     const [target] = rest
     if (!target) {
@@ -103,20 +115,27 @@ 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 (command === 'help' || args.flags.help) {
     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
   }
 
   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)}`)
@@ -141,6 +160,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/new.ts

@@ -1,20 +1,23 @@
 import type { Database } from 'bun:sqlite'
 import type { Config } from '../config/schema'
-import { newSession } from '../core/session'
-import { sessionDir } from '../paths'
+import { newSession, slugify } from '../core/session'
+import { basename, join, sessionDir } from '../paths'
 
 export async function cmdNew(db: Database, cfg: Config, cwd: string, goal: string): Promise<number> {
   const lead = cfg.roles.lead ?? 'claude'
-  const session = newSession(db, { cwd, goal: goal || 'untitled', lead })
+  const suffix = Bun.randomUUIDv7().slice(-4)
+  const slug = goal ? undefined : `${slugify(basename(cwd)).slice(0, 30)}-${suffix}`
+  const session = newSession(db, { cwd, goal, lead, slug })
   const dir = sessionDir(cwd, session.slug)
+  const ignore = Bun.file(join(cwd, '.konvoy', '.gitignore'))
+  if (!(await ignore.exists())) await Bun.write(ignore, '*\n!config.jsonc\n')
   // `konvoy rm` frees the slug but leaves these files - they are the user's. A new session under
   // an old slug adds its goal to the context and appends to the ledger; it truncates neither.
   const context = Bun.file(`${dir}/CONTEXT.md`)
+  const goalSection = session.goal ? `\n## Goal\n\n${session.goal}\n` : ''
   await Bun.write(
     context,
-    (await context.exists())
-      ? `${await context.text()}\n## Goal\n\n${session.goal}\n`
-      : `# ${session.slug}\n\n## Goal\n\n${session.goal}\n`,
+    (await context.exists()) ? `${await context.text()}${goalSection}` : `# ${session.slug}\n${goalSection}`,
   )
   const ledger = Bun.file(`${dir}/LEDGER.md`)
   if (!(await ledger.exists())) await Bun.write(ledger, `# Ledger - ${session.slug}\n`)

package/src/commands/rename.ts

@@ -0,0 +1,49 @@
+import type { Database } from 'bun:sqlite'
+import { slugify } from '../core/session'
+import { sessionDir } from '../paths'
+import { getSessionBySlug, lockOwner, renameSession } from '../store/queries'
+
+const isDir = async (path: string): Promise<boolean> => (await Bun.$`test -d ${path}`.quiet().nothrow()).exitCode === 0
+
+async function retitle(path: string, from: string, to: string): Promise<void> {
+  const file = Bun.file(path)
+  if (!(await file.exists())) return
+  const text = await file.text()
+  if (text.startsWith(from)) await Bun.write(file, to + text.slice(from.length))
+}
+
+export async function cmdRename(db: Database, from: string, to: string): Promise<number> {
+  const session = getSessionBySlug(db, from)
+  if (!session) {
+    console.error(`no konvoy session named "${from}"`)
+    return 2
+  }
+  const busy = lockOwner(db, session.id)
+  if (busy) {
+    console.error(`"${from}" has a turn running (${busy}) - wait for it to finish, then retry`)
+    return 2
+  }
+  const slug = slugify(to)
+  if (getSessionBySlug(db, slug)) {
+    console.error(`a session named "${slug}" already exists`)
+    return 2
+  }
+  const oldDir = sessionDir(session.cwd, from)
+  const newDir = sessionDir(session.cwd, slug)
+  if (await isDir(oldDir)) {
+    if (await isDir(newDir)) {
+      console.error(`${newDir} already exists - move it away first`)
+      return 2
+    }
+    const moved = await Bun.$`mv ${oldDir} ${newDir}`.quiet().nothrow()
+    if (moved.exitCode !== 0) {
+      console.error(`could not move ${oldDir} to ${newDir}: ${moved.stderr.toString().trim()}`)
+      return 1
+    }
+    await retitle(`${newDir}/CONTEXT.md`, `# ${from}\n`, `# ${slug}\n`)
+    await retitle(`${newDir}/LEDGER.md`, `# Ledger - ${from}\n`, `# Ledger - ${slug}\n`)
+  }
+  renameSession(db, session.id, slug)
+  console.log(`renamed ${from} -> ${slug}`)
+  return 0
+}

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/commands/table.ts

@@ -21,6 +21,7 @@ export const commandTable = [
     usage: 'rm <session> --yes',
     summary: 'delete a konvoy session (foreign sessions survive)',
   },
+  { name: 'rename', aliases: [], usage: 'rename <session> <new-name>', summary: 'rename a session; its .konvoy folder follows' },
   { name: 'roster', aliases: [], usage: 'roster', summary: 'who is in the convoy' },
   { name: 'usage', aliases: [], usage: 'usage [--all] [--chart]', summary: 'what this session spent, per agent' },
   { name: 'status', aliases: [], usage: 'status', summary: 'versions, auth and roster' },

package/src/core/prelude.ts

@@ -117,5 +117,5 @@ export function buildPrelude(db: Database, session: Session, facts: string, opts
 
   if (dropped > 0) turnBlocks.push(`(${dropped} earlier turn${dropped === 1 ? '' : 's'} not shown)`)
 
-  return [`goal: ${session.goal}`, facts, turnBlocks.join('\n\n')].filter(Boolean).join('\n\n')
+  return [session.goal ? `goal: ${session.goal}` : '', facts, turnBlocks.join('\n\n')].filter(Boolean).join('\n\n')
 }

package/src/paths.ts

@@ -14,6 +14,8 @@ export function join(...parts: string[]): string {
   return (absolute ? '/' : '') + segments.join('/')
 }
 
+export const basename = (p: string): string => p.split('/').filter(Boolean).at(-1) ?? ''
+
 export function dirname(p: string): string {
   const cut = p.lastIndexOf('/')
   if (cut < 0) return '.'

package/src/store/queries.ts

@@ -76,6 +76,14 @@ 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 })
+}
+
 export function deleteSession(db: Database, id: string): void {
   db.transaction(() => {
     db.query('DELETE FROM event WHERE turn_id IN (SELECT id FROM turn WHERE session_id = $id)').run({ id })