@doguyilmaz/konvoy 0.1.1

package/src/core/detect.ts

@@ -0,0 +1,211 @@
+import type { AgentId } from '../types'
+import { getAdapter } from '../adapters'
+import { stripControlChars } from '../adapters/types'
+import { home, join } from '../paths'
+
+export interface Detection {
+  agent: AgentId
+  installed: boolean
+  version: string | null
+  efforts?: readonly string[]
+}
+
+export interface AuthState {
+  agent: AgentId
+  authed: boolean | null
+  detail: string
+}
+
+export type Runner = (cmd: string[]) => Promise<{ stdout: string; exitCode: number }>
+
+export interface DetectDeps {
+  run: Runner
+  readText: (path: string) => Promise<string | null>
+}
+
+export function parseVersion(text: string): string | null {
+  return /(\d+\.\d+\.\d+)/.exec(text)?.[1] ?? null
+}
+
+interface AuthCheck {
+  args: string[]
+  ok: (stdout: string, exitCode: number) => boolean | null
+}
+
+const AUTH_CHECK: Record<AgentId, (bin?: string) => AuthCheck> = {
+  claude: (bin = 'claude') => ({
+    args: [bin, 'auth', 'status'],
+    ok: (stdout, exitCode) => {
+      if (!stdout) return null
+      try {
+        const json = JSON.parse(stdout) as { loggedIn?: unknown }
+        if (typeof json.loggedIn === 'boolean') return json.loggedIn
+      } catch {
+        // not JSON, fall through
+      }
+      return null
+    },
+  }),
+  codex: (bin = 'codex') => ({
+    args: [bin, 'login', 'status'],
+    ok: (stdout, exitCode) => {
+      if (!stdout || exitCode !== 0) return null
+      return stdout.includes('Logged in')
+    },
+  }),
+  kiro: (bin = 'kiro-cli') => ({
+    args: [bin, 'whoami'],
+    ok: (stdout, exitCode) => {
+      if (!stdout || exitCode !== 0) return null
+      return stdout.includes('Logged in')
+    },
+  }),
+  opencode: (bin = 'opencode') => ({
+    args: [bin, 'auth', 'list'],
+    ok: (stdout, exitCode) => {
+      if (exitCode !== 0) return null
+      return stdout.trim().length > 0
+    },
+  }),
+}
+
+async function codexEfforts(deps: DetectDeps, model?: string): Promise<readonly string[] | undefined> {
+  if (!model) return undefined
+  const raw = await deps.readText(join(home(), '.codex', 'models_cache.json'))
+  if (!raw) return undefined
+  try {
+    const cache = JSON.parse(raw) as { models?: unknown }
+    if (!Array.isArray(cache.models)) return undefined
+    // the real file (codex 0.155.1, 2026-09-21) keys models by `slug` and lists each level as
+    // `{ effort, description }` — see tests/fixtures/codex-models-cache.json
+    const hit = (cache.models as { slug?: string; supported_reasoning_levels?: unknown }[]).find(
+      (m) => m.slug === model,
+    )
+    if (!Array.isArray(hit?.supported_reasoning_levels)) return undefined
+    const levels = hit.supported_reasoning_levels.flatMap((l) =>
+      typeof (l as { effort?: unknown } | null)?.effort === 'string' ? [(l as { effort: string }).effort] : [],
+    )
+    return levels.length > 0 ? levels : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function authDetail(stdout: string, exitCode: number): string {
+  if (exitCode === 127) return 'not installed'
+  const trimmed = stdout.trim()
+  if (trimmed.startsWith('{')) {
+    try {
+      const parsed = JSON.parse(trimmed) as { loggedIn?: unknown; authMethod?: unknown }
+      const via = typeof parsed.authMethod === 'string' ? ` via ${stripControlChars(parsed.authMethod)}` : ''
+      if (parsed.loggedIn === true) return `logged in${via}`
+      if (parsed.loggedIn === false) return 'not logged in'
+    } catch {
+      // not the shape we expected; the first line is still better than nothing
+    }
+  }
+  return stripControlChars(trimmed.split('\n')[0] ?? '')
+}
+
+export async function detectWith(
+  deps: DetectDeps,
+  agent: AgentId,
+  opts: { model?: string; bin?: string } = {},
+): Promise<Detection> {
+  const adapter = getAdapter(agent)
+  const result = await deps.run([opts.bin ?? adapter.bin, '--version'])
+  const installed = result.exitCode === 0
+  const version = installed ? parseVersion(result.stdout) : null
+  const efforts = installed && agent === 'codex' ? await codexEfforts(deps, opts.model) : undefined
+  return { agent, installed, version, efforts }
+}
+
+export async function detectAuthWith(
+  deps: DetectDeps,
+  agent: AgentId,
+  bin?: string,
+): Promise<AuthState> {
+  const check = AUTH_CHECK[agent](bin)
+  const result = await deps.run(check.args)
+  const detail = authDetail(result.stdout, result.exitCode)
+  if (result.exitCode === 127) {
+    return { agent, authed: null, detail }
+  }
+  const authed = check.ok(result.stdout, result.exitCode)
+  return { agent, authed, detail }
+}
+
+function memo<K, V>(cacheMap: Map<K, Promise<V>>, key: K, f: () => Promise<V>): Promise<V> {
+  const hit = cacheMap.get(key)
+  if (hit) return hit
+  const pending = f()
+    .then((v) => {
+      cacheMap.set(key, Promise.resolve(v))
+      return v
+    })
+    .catch((e) => {
+      cacheMap.delete(key)
+      throw e
+    })
+  cacheMap.set(key, pending)
+  return pending
+}
+
+function realDeps(): DetectDeps {
+  return {
+    run: async (cmd) => {
+      try {
+        const proc = Bun.spawn(cmd, { stdout: 'pipe', stderr: 'pipe', timeout: 10_000 })
+        const stdout = await new Response(proc.stdout).text()
+        const stderr = await new Response(proc.stderr).text()
+        const exitCode = await proc.exited
+        return { stdout: stdout || stderr, exitCode }
+      } catch {
+        return { stdout: '', exitCode: 127 }
+      }
+    },
+    readText: async (path) => {
+      try {
+        const file = Bun.file(path)
+        return (await file.exists()) ? file.text() : null
+      } catch {
+        return null
+      }
+    },
+  }
+}
+
+const detectCacheMap = new Map<string, Promise<Detection>>()
+const detectAuthCacheMap = new Map<string, Promise<AuthState>>()
+
+// Real detection shares one memo; each injected deps object gets its own, so a fake answering in
+// one place is never handed to another.
+const depsIds = new WeakMap<DetectDeps, number>()
+let nextDepsId = 0
+function scope(deps?: DetectDeps): string {
+  if (!deps) return 'real'
+  let id = depsIds.get(deps)
+  if (id === undefined) depsIds.set(deps, (id = ++nextDepsId))
+  return String(id)
+}
+
+export function clearDetectCache(): void {
+  detectCacheMap.clear()
+  detectAuthCacheMap.clear()
+}
+
+export interface DetectOptions {
+  model?: string
+  bin?: string
+  deps?: DetectDeps
+}
+
+export async function detect(agent: AgentId, opts: DetectOptions = {}): Promise<Detection> {
+  const key = `${scope(opts.deps)}\u0000${agent}\u0000${opts.model ?? ''}\u0000${opts.bin ?? ''}`
+  return memo(detectCacheMap, key, () => detectWith(opts.deps ?? realDeps(), agent, opts))
+}
+
+export async function detectAuth(agent: AgentId, opts: DetectOptions = {}): Promise<AuthState> {
+  const key = `${scope(opts.deps)}\u0000${agent}\u0000${opts.bin ?? ''}`
+  return memo(detectAuthCacheMap, key, () => detectAuthWith(opts.deps ?? realDeps(), agent, opts.bin))
+}

package/src/core/facts.ts

@@ -0,0 +1,113 @@
+import type { Database } from 'bun:sqlite'
+import type { Session } from '../types'
+import { usageForSession } from '../store/queries'
+import { spend } from '../format'
+
+export interface Facts {
+  commits: { sha: string; subject: string }[]
+  files: { path: string; added: number; removed: number }[]
+  agents: { agent: string; turns: number; spend: string }[]
+}
+
+export interface FactsDeps {
+  git: (args: string[], cwd: string) => Promise<string>
+}
+
+function parseLog(output: string): { sha: string; subject: string }[] {
+  return output
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const sp = line.indexOf(' ')
+      return sp === -1 ? { sha: line, subject: '' } : { sha: line.slice(0, sp), subject: line.slice(sp + 1) }
+    })
+}
+
+const STAT_LINE = /^\s*(.+?)\s*\|\s*(\d+)\s*(\+*)(-*)\s*$/
+
+function parseDiffStat(output: string): { path: string; added: number; removed: number }[] {
+  const files: { path: string; added: number; removed: number }[] = []
+  for (const line of output.split('\n')) {
+    const m = STAT_LINE.exec(line)
+    if (!m) continue
+    const total = Number(m[2])
+    const plus = m[3]!.length
+    const minus = m[4]!.length
+    // the +/- bar is drawn proportionally to the real counts, not one char per change,
+    // so the split has to be recovered from the bar's ratio rather than counted directly
+    const added = plus + minus === 0 ? total : Math.round((total * plus) / (plus + minus))
+    files.push({ path: m[1]!, added, removed: total - added })
+  }
+  return files
+}
+
+export async function collectFacts(deps: FactsDeps, db: Database, session: Session): Promise<Facts> {
+  const [logOut, diffOut] = await Promise.all([
+    deps.git(['log', '--oneline', '-n', '100', '--since', new Date(session.createdAt).toISOString()], session.cwd),
+    deps.git(['diff', '--stat'], session.cwd),
+  ])
+  const agents = usageForSession(db, session.id).map((r) => ({ agent: r.agent, turns: r.turns, spend: spend(r) }))
+  return { commits: parseLog(logOut), files: parseDiffStat(diffOut), agents }
+}
+
+// A field is quoted only when it has to be. 48% of this repository's own commit subjects
+// contain a comma, so an unquoted row is the common case, not the edge one — and a shifted
+// row makes every number after it wrong while still looking like a table.
+function cell(value: string): string {
+  return /[",\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value
+}
+
+// The turns half of the prelude is capped (prelude.ts); this half must be too, or a busy
+// repository prepends its whole history to every prompt for every agent.
+const FACTS_ROW_CAP = 30
+
+function section(name: string, fields: string[], rows: string[][]): string {
+  const shown = rows.slice(0, FACTS_ROW_CAP)
+  const lines = [`${name}[${shown.length}]{${fields.join(',')}}:`, ...shown.map((r) => r.map(cell).join(','))]
+  if (rows.length > shown.length) lines.push(`(+${rows.length - shown.length} more ${name})`)
+  return lines.join('\n')
+}
+
+export function formatFacts(facts: Facts): string {
+  const blocks: string[] = []
+  if (facts.commits.length > 0) {
+    blocks.push(section('commits', ['sha', 'subject'], facts.commits.map((c) => [c.sha, c.subject])))
+  }
+  if (facts.files.length > 0) {
+    blocks.push(
+      section(
+        'files',
+        ['path', 'added', 'removed'],
+        facts.files.map((f) => [f.path, String(f.added), String(f.removed)]),
+      ),
+    )
+  }
+  if (facts.agents.length > 0) {
+    blocks.push(
+      section(
+        'agents',
+        ['agent', 'turns', 'spend'],
+        facts.agents.map((a) => [a.agent, String(a.turns), a.spend]),
+      ),
+    )
+  }
+  return blocks.join('\n\n')
+}
+
+export function realFactsDeps(): FactsDeps {
+  return {
+    git: async (args, cwd) => {
+      try {
+        // stderr is never read, so it is not piped — a chatty git would fill the pipe and block;
+        // and a git that hangs must not hang the turn
+        const proc = Bun.spawn(['git', ...args], { cwd, stdout: 'pipe', stderr: 'ignore', timeout: 10_000 })
+        const stdout = await new Response(proc.stdout).text()
+        await proc.exited
+        return stdout
+      } catch {
+        return ''
+      }
+    },
+  }
+}

package/src/core/gate.ts

@@ -0,0 +1,73 @@
+import type { Database } from 'bun:sqlite'
+import type { Config } from '../config/schema'
+import type { Session } from '../types'
+import { setGateResult, turnExitCode } from '../store/queries'
+import { DEFAULT_KILL_GRACE_MS, escalateKill } from './children'
+
+// A quality check the user chose to run — konvoy has no model of its own, so it never
+// grades the work itself. Bounded so a hung suite can't block konvoy forever.
+const GATE_TIMEOUT_MS = 5 * 60 * 1000
+
+export async function runGate(
+  db: Database,
+  cfg: Config,
+  session: Session,
+  turnId: string,
+  opts: { timeoutMs?: number; killGraceMs?: number } = {},
+): Promise<void> {
+  const command = cfg.gate.command
+  if (!command) return
+  // A turn with nothing for the gate to judge — running it now would blame the block on the work.
+  if (turnExitCode(db, turnId) !== 0) return
+
+  const cmd = splitCommand(command)
+
+  try {
+    const proc = Bun.spawn(cmd, {
+      cwd: session.cwd,
+      stdout: 'ignore',
+      stderr: 'ignore',
+      timeout: opts.timeoutMs ?? GATE_TIMEOUT_MS,
+      killSignal: 'SIGTERM',
+    })
+    const cancelEscalation = escalateKill(proc, (opts.timeoutMs ?? GATE_TIMEOUT_MS) + (opts.killGraceMs ?? DEFAULT_KILL_GRACE_MS))
+    try {
+      const exitCode = await proc.exited
+      setGateResult(db, turnId, exitCode === 0)
+    } finally {
+      cancelEscalation()
+    }
+  } catch {
+    // could not spawn: a misconfiguration, not a verdict on the work, so nothing is recorded
+  }
+}
+
+// Whitespace outside quotes separates arguments; a quoted run is one argument, quotes removed.
+// No shell is involved — the gate is the user's own command, but it still deserves its quotes.
+export function splitCommand(command: string): string[] {
+  const out: string[] = []
+  let current = ''
+  let quote: string | null = null
+  let quoted = false
+  for (const ch of command) {
+    if (quote) {
+      if (ch === quote) quote = null
+      else current += ch
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      quoted = true
+      continue
+    }
+    if (/\s/.test(ch)) {
+      if (current || quoted) out.push(current)
+      current = ''
+      quoted = false
+      continue
+    }
+    current += ch
+  }
+  if (current || quoted) out.push(current)
+  return out
+}

package/src/core/prelude.ts

@@ -0,0 +1,121 @@
+import type { Database } from 'bun:sqlite'
+import type { Session } from '../types'
+
+export interface Envelope {
+  to: string | null
+  task: string
+  open: string[]
+  decisions: string[]
+}
+
+// Sentinels rather than JSON: a model wraps JSON in prose or fences, and a missing field
+// should degrade to empty rather than fail a parse.
+const ENVELOPE_RE = /<<<konvoy\n([\s\S]*?)>>>/
+const RECIPIENT = /^[a-z][a-z0-9_-]*$/i
+
+export function parseEnvelope(final: string): Envelope | null {
+  const match = ENVELOPE_RE.exec(final)
+  if (!match) return null
+
+  const env: Envelope = { to: null, task: '', open: [], decisions: [] }
+  let list: string[] | null = null
+
+  for (const raw of (match[1] ?? '').split('\n')) {
+    const line = raw.trim()
+    if (line === '') continue
+
+    const item = /^-\s*(.*)$/.exec(line)
+    if (item && list) {
+      list.push(item[1]!.trim())
+      continue
+    }
+
+    const kv = /^([a-zA-Z]+):\s*(.*)$/.exec(line)
+    if (!kv) {
+      list = null
+      continue
+    }
+    const key = kv[1]!
+    const value = kv[2]!.trim()
+    switch (key) {
+      case 'to':
+        // a recipient is an agent id or a role name — a bare identifier. The delegation
+        // instruction quotes the format with "<agent id or role>" in this slot, and an agent
+        // explaining what it is not doing repeats it; that names nobody and is no handoff.
+        env.to = RECIPIENT.test(value) ? value : null
+        list = null
+        break
+      case 'task':
+        env.task = value
+        list = null
+        break
+      case 'open':
+        list = env.open
+        break
+      case 'decisions':
+        list = env.decisions
+        break
+      default:
+        list = null
+    }
+  }
+
+  return env
+}
+
+interface TurnRow {
+  agent: string
+  prompt: string
+  final: string
+}
+
+function renderPair(t: TurnRow): string {
+  return `${t.agent} was asked: ${t.prompt}\n${t.agent} answered: ${t.final}`
+}
+
+function renderEnvelope(agent: string, env: Envelope): string {
+  const lines = [`${agent} handed off to ${env.to ?? 'the next agent'}:`, `task: ${env.task}`]
+  if (env.open.length > 0) lines.push('open:', ...env.open.map((o) => `- ${o}`))
+  if (env.decisions.length > 0) lines.push('decisions:', ...env.decisions.map((d) => `- ${d}`))
+  return lines.join('\n')
+}
+
+// Order is goal, then facts, then recent turns: stable first, volatile last, because prompt
+// caching discounts a stable prefix by roughly an order of magnitude and a prelude that
+// reshuffles itself every turn pays full price for all of it.
+export function buildPrelude(db: Database, session: Session, facts: string, opts: { recent: number }): string {
+  const total = (
+    db.query('SELECT COUNT(*) AS c FROM turn WHERE session_id = $id').get({ id: session.id }) as { c: number }
+  ).c
+  if (total === 0) return ''
+
+  const rows = db
+    .query('SELECT agent, prompt, final FROM turn WHERE session_id = $id ORDER BY started_at DESC, rowid DESC LIMIT $limit')
+    .all({ id: session.id, limit: opts.recent }) as TurnRow[]
+  const oldestFirst = [...rows].reverse()
+  const dropped = total - rows.length
+
+  const last = oldestFirst[oldestFirst.length - 1]
+  const envelope = last ? parseEnvelope(last.final) : null
+
+  const turnBlocks: string[] = []
+  for (let i = 0; i < oldestFirst.length - 1; i++) turnBlocks.push(renderPair(oldestFirst[i]!))
+
+  // the same test followHandoff applies: a block with no recipient handed nothing to anyone,
+  // so the answer it sits in is what the next agent must see
+  if (!last) {
+    // recent: 0 — only the goal, the facts and the count of what was left out
+  } else if (envelope?.to) {
+    turnBlocks.push(renderEnvelope(last.agent, envelope))
+  } else {
+    turnBlocks.push(renderPair(last))
+    // The cooperative case (section 21) has a sender who can still speak; failover does not.
+    // A receiver that believes its context is complete proceeds on half the picture, so the
+    // gap is stated plainly instead of silently filled with a prompt-and-answer transcript.
+    turnBlocks.push("the previous agent's intent was not recorded here — only what was asked and answered is known.")
+  }
+
+  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')
+}