@doguyilmaz/konvoy 0.1.1

package/src/commands/doctor.ts

@@ -0,0 +1,104 @@
+import type { Config } from '../config/schema'
+import { agentIds, getAdapter } from '../adapters'
+import type { AgentId } from '../types'
+import { resolveAgent } from '../config/load'
+import { detect, detectAuth, type DetectDeps } from '../core/detect'
+import { clampEffort } from '../adapters/effort'
+import { loginHint } from './send'
+
+// `which -a` prints one line per PATH entry, so a directory listed twice repeats the same path
+export function distinctPaths(stdout: string): string[] {
+  return [...new Set(stdout.trim().split('\n').filter(Boolean))]
+}
+
+// engine, policy.maxDelegationDepth and policy.isolation are in the schema and the spec, but
+// nothing reads them yet — the delegation work will. Comparing the parsed policy values against
+// their schema defaults is an approximation (a value set explicitly equal to the default reads
+// as unset), acceptable for an informational line with no behavioural effect.
+export function acceptedButUnusedKeys(cfg: Config): string[] {
+  const keys: string[] = []
+  if (cfg.policy.maxDelegationDepth !== 3) keys.push('policy.maxDelegationDepth')
+  if (cfg.policy.isolation !== 'serial') keys.push('policy.isolation')
+  for (const agent of agentIds) {
+    if (cfg.agents[agent]?.engine !== undefined) keys.push(`agents.${agent}.engine`)
+  }
+  return keys
+}
+
+export async function cmdDoctor(cfg: Config, deps?: DetectDeps): Promise<number> {
+  let problems = 0
+  const models = new Map<string, string[]>()
+  const required = new Set<AgentId>(
+    [cfg.roles.lead ?? 'claude', cfg.roles.implementer, cfg.roles.reviewer, cfg.roles.researcher].filter(
+      (a): a is AgentId => a !== undefined,
+    ),
+  )
+
+  for (const agent of agentIds) {
+    const settings = resolveAgent(cfg, agent)
+    if (!settings.enabled) {
+      if (required.has(agent)) {
+        console.log(`x ${agent}: disabled in config but named by a role`)
+        problems++
+      } else {
+        console.log(`- ${agent}: disabled in config`)
+      }
+      continue
+    }
+
+    const d = await detect(agent, { model: settings.model, bin: settings.bin, deps })
+    if (!d.installed) {
+      if (required.has(agent)) {
+        console.log(`x ${agent}: not installed`)
+        problems++
+      } else {
+        console.log(`- ${agent}: not installed`)
+      }
+      continue
+    }
+    const auth = await detectAuth(agent, { bin: settings.bin, deps })
+    if (auth.authed === false) {
+      if (required.has(agent)) {
+        console.log(`x ${agent}: ${auth.detail} — ${loginHint(agent)}`)
+        problems++
+      } else {
+        console.log(`- ${agent}: ${auth.detail} — ${loginHint(agent)}`)
+      }
+      continue
+    }
+
+    const clamp = clampEffort(settings.effort, d.efforts)
+    if (clamp.clamped) {
+      console.log(`! ${agent}: effort "${settings.effort}" is unsupported here, using "${clamp.value}"`)
+    }
+
+    if (agent === 'opencode' && !settings.model) {
+      console.log(`! opencode: no model configured — it returns HTTP 403 without an explicit -m`)
+    }
+
+    const shadow = Bun.spawnSync(['which', '-a', settings.bin ?? getAdapter(agent).bin])
+    const paths = distinctPaths(new TextDecoder().decode(shadow.stdout))
+    if (paths.length > 1 && !settings.bin) {
+      console.log(`! ${agent}: ${paths.length} binaries on PATH, "${paths[0]}" wins — set agents.${agent}.bin to be explicit`)
+    }
+
+    if (settings.model) {
+      models.set(settings.model, [...(models.get(settings.model) ?? []), agent])
+    }
+    console.log(`ok ${agent}: ${d.version}${settings.model ? ` (${settings.model})` : ''}`)
+  }
+
+  for (const [model, users] of models) {
+    if (users.length > 1) {
+      console.log(`! ${users.join(' and ')} both run ${model} — they will not disagree with each other`)
+    }
+  }
+
+  const unused = acceptedButUnusedKeys(cfg)
+  if (unused.length > 0) {
+    console.log(`i ${unused.join(', ')} — accepted but not yet used`)
+  }
+
+  console.log(problems === 0 ? '\nno problems found' : `\n${problems} problem(s) found`)
+  return problems === 0 ? 0 : 1
+}

package/src/commands/ls.ts

@@ -0,0 +1,15 @@
+import type { Database } from 'bun:sqlite'
+import { boundBindingCounts, listSessions } from '../store/queries'
+
+export function cmdLs(db: Database): number {
+  const sessions = listSessions(db)
+  if (sessions.length === 0) {
+    console.log('no konvoy sessions yet')
+    return 0
+  }
+  const bound = boundBindingCounts(db)
+  for (const s of sessions) {
+    console.log(`${s.slug}  ${bound.get(s.id) ?? 0}/4 bound  ${s.cwd}  ${s.goal}`)
+  }
+  return 0
+}

package/src/commands/new.ts

@@ -0,0 +1,24 @@
+import type { Database } from 'bun:sqlite'
+import type { Config } from '../config/schema'
+import { newSession } from '../core/session'
+import { 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 dir = sessionDir(cwd, session.slug)
+  // `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`)
+  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`,
+  )
+  const ledger = Bun.file(`${dir}/LEDGER.md`)
+  if (!(await ledger.exists())) await Bun.write(ledger, `# Ledger — ${session.slug}\n`)
+  console.log(`created session ${session.slug} (lead: ${lead})`)
+  console.log(dir)
+  return 0
+}

package/src/commands/resume.ts

@@ -0,0 +1,14 @@
+import type { Database } from 'bun:sqlite'
+import type { Config } from '../config/schema'
+import { currentSession, getSessionBySlug, touchSession } from '../store/queries'
+import { cmdRoster } from './roster'
+
+export function cmdResume(db: Database, cfg: Config, cwd: string, slug?: string): number {
+  const session = slug ? getSessionBySlug(db, slug) : currentSession(db, cwd)
+  if (!session) {
+    console.error(slug ? `no konvoy session named "${slug}"` : 'no konvoy session in this directory')
+    return 2
+  }
+  touchSession(db, session.id)
+  return cmdRoster(db, cfg, session.cwd, session.slug)
+}

package/src/commands/rm.ts

@@ -0,0 +1,28 @@
+import type { Database } from 'bun:sqlite'
+import { deleteSession, getSessionBySlug, listBindings, lockOwner } from '../store/queries'
+
+export function cmdRm(db: Database, cwd: string, slug: string, opts: { yes: boolean }): number {
+  const session = getSessionBySlug(db, slug)
+  if (!session) {
+    console.error(`no konvoy session named "${slug}"`)
+    return 2
+  }
+  const busy = lockOwner(db, session.id)
+  if (busy) {
+    console.error(`"${slug}" has a turn running (${busy}) — wait for it to finish, then retry`)
+    return 2
+  }
+  const bound = listBindings(db, session.id).filter((b) => b.foreignId)
+  if (!opts.yes) {
+    console.error(`this deletes konvoy session "${slug}" and its ${bound.length} binding(s)`)
+    console.error(`the sessions inside each CLI are NOT deleted — re-run with --yes to proceed`)
+    return 2
+  }
+  deleteSession(db, session.id)
+  console.log(`removed ${slug}`)
+  if (bound.length > 0) {
+    console.log(`the following foreign sessions still exist and can be opened directly:`)
+    for (const b of bound) console.log(`  ${b.agent}: ${b.foreignId}`)
+  }
+  return 0
+}

package/src/commands/roster.ts

@@ -0,0 +1,37 @@
+import type { Database } from 'bun:sqlite'
+import type { Config } from '../config/schema'
+import { agentIds } from '../adapters'
+import { resolveAgent } from '../config/load'
+import { currentSession, getSessionBySlug, listBindings } from '../store/queries'
+import { duplicateModels, formatRoster, type RosterRow } from '../format'
+
+export function cmdRoster(db: Database, cfg: Config, cwd: string, slug?: string): number {
+  const session = slug ? getSessionBySlug(db, slug) : currentSession(db, cwd)
+  if (!session) {
+    console.error('no konvoy session here — run `konvoy new "<goal>"` first')
+    return 2
+  }
+
+  const bindings = new Map(listBindings(db, session.id).map((b) => [b.agent, b]))
+  const rows: RosterRow[] = agentIds.map((agent) => {
+    const settings = resolveAgent(cfg, agent)
+    const binding = bindings.get(agent) ?? null
+    return {
+      agent,
+      status: !settings.enabled ? 'disabled' : (binding?.status ?? 'unbound'),
+      model: settings.model ?? '',
+      effort: settings.effort,
+      foreignId: binding?.foreignId ?? null,
+      turns: binding?.turns ?? 0,
+      costUsd: binding?.costUsd ?? 0,
+      credits: binding?.credits ?? 0,
+    }
+  })
+
+  console.log(`session ${session.slug} — ${session.goal}`)
+  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`)
+  }
+  return 0
+}

package/src/commands/send.ts

@@ -0,0 +1,79 @@
+import type { Database } from 'bun:sqlite'
+import type { Config } from '../config/schema'
+import type { AgentId } from '../types'
+import { agentIds } from '../adapters'
+import { currentSession, getSessionBySlug } from '../store/queries'
+import { send } from '../core/session'
+import { oneLine, safeText } from '../adapters/types'
+import type { TurnResult } from '../core/turn'
+
+export async function cmdSend(
+  db: Database,
+  cfg: Config,
+  cwd: string,
+  agent: string,
+  prompt: string,
+  slug?: string,
+): Promise<number> {
+  if (!agentIds.includes(agent as AgentId)) {
+    console.error(`unknown agent "${agent}" — expected one of ${agentIds.join(', ')}`)
+    return 2
+  }
+  const session = slug ? getSessionBySlug(db, slug) : currentSession(db, cwd)
+  if (!session) {
+    console.error('no konvoy session here — run `konvoy new "<goal>"` first')
+    return 2
+  }
+
+  let result: TurnResult
+  try {
+    result = await send({ db, cfg }, session, agent as AgentId, prompt, {
+      onEvent: (e) => {
+        if (e.t === 'tool') console.error(`  · ${oneLine(e.name, 120)}`)
+      },
+    })
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 2
+  }
+
+  const outcome = decideOutcome(agent as AgentId, result)
+  for (const line of outcome.stderrLines) console.error(line)
+  if (outcome.stdout !== null) console.log(outcome.stdout)
+  return outcome.code
+}
+
+export interface SendOutcome {
+  code: number
+  stdout: string | null
+  stderrLines: string[]
+}
+
+// The exit code is decided here, once, from the same two facts turn.ts keeps separate: whether
+// output was produced (result.final) and whether the agent is now blocked (result.error.kind).
+// A turn that answered and then hit a limit is both successful and blocked — it prints what it
+// produced, plus the one line saying the agent can't keep going, and exits 0.
+export function decideOutcome(agent: AgentId, result: TurnResult): SendOutcome {
+  if (result.error) {
+    const blocked = result.error.kind === 'auth' || result.error.kind === 'rate'
+    if (blocked && result.final.trim() !== '') {
+      const stderrLines = [`${agent} is blocked (${result.error.kind}): ${oneLine(result.error.message)}`]
+      if (result.error.kind === 'auth') stderrLines.push(loginHint(agent))
+      return { code: 0, stdout: safeText(result.final), stderrLines }
+    }
+    const stderrLines = [`${agent} failed (${result.error.kind}): ${oneLine(result.error.message)}`]
+    if (result.error.kind === 'auth') stderrLines.push(loginHint(agent))
+    return { code: 1, stdout: null, stderrLines }
+  }
+  return { code: 0, stdout: safeText(result.final), stderrLines: [] }
+}
+
+export function loginHint(agent: AgentId): string {
+  const hints: Record<AgentId, string> = {
+    claude: 'run: claude auth',
+    codex: 'run: codex login',
+    kiro: 'run: kiro-cli login',
+    opencode: 'run: opencode providers',
+  }
+  return hints[agent]
+}

package/src/commands/status.ts

@@ -0,0 +1,35 @@
+import type { Database } from 'bun:sqlite'
+import type { Config } from '../config/schema'
+import { agentIds } from '../adapters'
+import { resolveAgent } from '../config/load'
+import { detect, detectAuth } from '../core/detect'
+import { formatVersions, type AgentStatusRow } from '../format'
+import { cmdRoster } from './roster'
+
+export async function cmdStatus(
+  db: Database,
+  cfg: Config,
+  cwd: string,
+  slug?: string,
+  opts: { roster?: boolean } = {},
+): Promise<number> {
+  const rows: AgentStatusRow[] = await Promise.all(
+    agentIds.map(async (agent) => {
+      const settings = resolveAgent(cfg, agent)
+      const found = await detect(agent, { model: settings.model, bin: settings.bin })
+      const auth = found.installed
+        ? await detectAuth(agent, { bin: settings.bin })
+        : { agent, authed: null, detail: 'not installed' }
+      return { agent, installed: found.installed, version: found.version, authed: auth.authed, detail: auth.detail }
+    }),
+  )
+  console.log(formatVersions(rows))
+  for (const r of rows) {
+    if (!r.installed) console.log(`warning: ${r.agent} is not installed — it will be skipped`)
+    else if (r.authed === false) console.log(`warning: ${r.agent}: ${r.detail}`)
+  }
+  // status reports; it does not judge. A directory with no session is not a failure of the
+  // command, and cmdRoster has already said so on stderr.
+  if (opts.roster !== false) cmdRoster(db, cfg, cwd, slug)
+  return 0
+}

package/src/commands/table.ts

@@ -0,0 +1,75 @@
+// Single source of truth for konvoy's command surface: name, aliases, usage line and
+// one-line summary. src/cli.ts derives both its dispatch table and its USAGE text from
+// this array, and tests/docs.test.ts checks README.md against it, so a command can't be
+// documented without existing, or exist without being documented.
+export interface CommandSpec {
+  readonly name: string
+  readonly aliases: readonly string[]
+  readonly usage: string
+  readonly summary: string
+}
+
+export const commandTable = [
+  { name: 'new', aliases: ['start'], usage: 'new "<goal>"', summary: 'create a session in this directory' },
+  { name: 'send', aliases: [], usage: 'send <agent> "<msg>"', summary: 'run one turn against one agent' },
+  { name: 'ls', aliases: ['sessions'], usage: 'ls', summary: 'list sessions' },
+  { name: 'resume', aliases: [], usage: 'resume [session]', summary: 'make a session current and show its roster' },
+  { name: 'config', aliases: [], usage: 'config get|set', summary: 'read or write layered configuration' },
+  {
+    name: 'rm',
+    aliases: [],
+    usage: 'rm <session> --yes',
+    summary: 'delete a konvoy session (foreign sessions survive)',
+  },
+  { 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' },
+  {
+    name: 'attach',
+    aliases: [],
+    usage: 'attach <agent> [--id <session-id>]',
+    summary: "open that agent's own interface, same session",
+  },
+  {
+    name: 'doctor',
+    aliases: [],
+    usage: 'doctor',
+    summary: 'check installs, logins, effort and model overlap',
+  },
+  {
+    name: 'update',
+    aliases: [],
+    usage: 'update [--all]',
+    summary: 'update konvoy, and with --all the agent CLIs',
+  },
+  { name: 'version', aliases: [], usage: 'version', summary: 'konvoy and agent versions' },
+  { name: 'dashboard', aliases: [], usage: 'dashboard [--port N]', summary: 'open a local page with the same numbers' },
+] as const satisfies readonly CommandSpec[]
+
+export type CommandName = (typeof commandTable)[number]['name']
+
+const aliasToName = new Map<string, CommandName>()
+for (const c of commandTable) {
+  aliasToName.set(c.name, c.name)
+  for (const alias of c.aliases) aliasToName.set(alias, c.name)
+}
+
+// Resolves a typed word (a command name or one of its aliases) to its canonical command
+// name, or undefined if it isn't a known command at all.
+export function resolveCommandName(word: string): CommandName | undefined {
+  return aliasToName.get(word)
+}
+
+// The two-column command listing used by USAGE, generated from the table so it can't
+// drift from what dispatch actually supports.
+export function formatCommandList(): string {
+  const prefixes = commandTable.map((c) => `konvoy ${c.usage}`)
+  const width = Math.max(...prefixes.map((p) => p.length))
+  return commandTable
+    .map((c, i) => {
+      const prefix = prefixes[i]!
+      const gap = ' '.repeat(Math.max(2, width - prefix.length))
+      return `  ${prefix}${gap}${c.summary}`
+    })
+    .join('\n')
+}

package/src/commands/update.ts

@@ -0,0 +1,72 @@
+import type { AgentId } from '../types'
+import { agentIds } from '../adapters'
+import { detect, type Detection, clearDetectCache } from '../core/detect'
+import { resolveAgent } from '../config/load'
+import type { Config } from '../config/schema'
+
+const COMMANDS: Record<AgentId, string[]> = {
+  claude: ['claude', 'update'],
+  codex: ['codex', 'update'],
+  kiro: ['kiro-cli', 'update'],
+  opencode: ['opencode', 'upgrade'],
+}
+
+export function updateCommand(agent: AgentId, bin?: string): string[] {
+  const [name, ...rest] = COMMANDS[agent]
+  return [bin ?? name!, ...rest]
+}
+
+export interface UpdateDeps {
+  detect: (agent: AgentId, opts: { bin?: string }) => Promise<Detection>
+  spawn: (argv: string[]) => Promise<number>
+}
+
+const realUpdateDeps: UpdateDeps = {
+  detect: (agent, opts) => detect(agent, opts),
+  spawn: async (argv) => {
+    const proc = Bun.spawn(argv, { stdio: ['inherit', 'inherit', 'inherit'] })
+    return proc.exited
+  },
+}
+
+export async function cmdUpdate(
+  cfg: Config,
+  opts: { all: boolean },
+  deps: UpdateDeps = realUpdateDeps,
+): Promise<number> {
+  if (!opts.all) {
+    // konvoy does not update itself — it follows the channel it was installed from
+    const channel = Bun.isStandaloneExecutable
+      ? 'brew upgrade --cask konvoy, or download the latest release'
+      : 'bun add -g @doguyilmaz/konvoy@latest, or bun run build in a checkout'
+    console.log(`to update konvoy: ${channel}`)
+    console.log('to update the agent CLIs: konvoy update --all')
+    return 0
+  }
+
+  let failures = 0
+  for (const agent of agentIds) {
+    const settings = resolveAgent(cfg, agent)
+    if (!settings.enabled) {
+      console.log(`- ${agent}: disabled in config, skipping`)
+      continue
+    }
+    const before = await deps.detect(agent, { bin: settings.bin })
+    if (!before.installed) {
+      console.log(`- ${agent}: not installed, skipping`)
+      continue
+    }
+    console.log(`updating ${agent} (${before.version})...`)
+    const code = await deps.spawn(updateCommand(agent, settings.bin))
+    if (code !== 0) {
+      console.log(`! ${agent}: update exited with ${code}`)
+      failures++
+      continue
+    }
+    // the memo would hand back the pre-update detection; the version line must come from a fresh --version
+    clearDetectCache()
+    const after = await deps.detect(agent, { bin: settings.bin })
+    console.log(`ok ${agent}: ${before.version} -> ${after.version}`)
+  }
+  return failures === 0 ? 0 : 1
+}

package/src/commands/usage.ts

@@ -0,0 +1,77 @@
+import type { Database } from 'bun:sqlite'
+import {
+  currentSession,
+  getSessionBySlug,
+  turnsPerDay,
+  turnsPerDayByAgent,
+  usageAcrossSessions,
+  usageByAgentModel,
+  usageForSession,
+  type UsageRow,
+} from '../store/queries'
+import { formatUsage } from '../format'
+import { agentSparklines, heatmap, shareBars } from '../chart'
+import { isPricingConfigured } from '../pricing'
+import type { Config } from '../config/schema'
+import type { Session } from '../types'
+
+// the SPEND column mixes dollars and credits, so every table that shows it carries this line
+const UNITS = "spend is in each agent's own unit; a dash means the CLI reported none"
+
+export function cmdUsage(
+  db: Database,
+  cfg: Config,
+  cwd: string,
+  opts: { all: boolean; slug?: string; chart?: boolean },
+): number {
+  let session: Session | null = null
+  let rows: UsageRow[]
+
+  if (opts.all) {
+    rows = usageAcrossSessions(db)
+    if (rows.length === 0) {
+      console.log('no turns recorded yet')
+      return 0
+    }
+    console.log('all sessions')
+  } else {
+    session = opts.slug ? getSessionBySlug(db, opts.slug) : currentSession(db, cwd)
+    if (!session) {
+      console.error('no konvoy session here — run `konvoy new "<goal>"` first')
+      return 2
+    }
+    rows = usageForSession(db, session.id)
+    if (rows.length === 0) {
+      console.log(`session ${session.slug} — no turns yet`)
+      return 0
+    }
+    console.log(`session ${session.slug}`)
+  }
+
+  const sessionId = opts.all ? undefined : session?.id
+
+  console.log(formatUsage(rows, cfg.pricing, usageByAgentModel(db, sessionId)))
+  console.log(
+    isPricingConfigured(cfg.pricing)
+      ? `${UNITS}; ~USD is estimated from rates configured as of ${cfg.pricing.asOf || 'an unspecified date'}`
+      : UNITS,
+  )
+
+  if (opts.chart) {
+    console.log('\nturns per day')
+    console.log(heatmap(turnsPerDay(db, sessionId)))
+    console.log('\nshare of turns')
+    console.log(shareBars(rows.map((r) => ({ label: r.agent, value: r.turns }))))
+
+    const perAgent = agentSparklines(turnsPerDayByAgent(db, sessionId))
+    if (perAgent.length > 0) {
+      console.log('\nturns per day by agent')
+      const labelWidth = Math.max(...perAgent.map((r) => r.agent.length))
+      for (const { agent, line } of perAgent) {
+        console.log(`${agent.padEnd(labelWidth)}  ${line}`)
+      }
+    }
+  }
+
+  return 0
+}