@doguyilmaz/konvoy 0.1.1

package/src/config/load.ts

@@ -0,0 +1,335 @@
+import {
+  agentIds,
+  configSchema,
+  type AgentId,
+  type Config,
+  type Effort,
+  type Harness,
+  type Permission,
+  type Style,
+} from './schema'
+import { configDir, home, join } from '../paths'
+
+export const globalConfigPath = (): string => join(configDir(), 'config.jsonc')
+export const projectConfigPath = (cwd: string): string => join(cwd, '.konvoy', 'config.jsonc')
+
+export interface AgentSettings {
+  enabled: boolean
+  model?: string
+  effort: Effort
+  permission: Permission
+  harness: Harness
+  bin?: string
+  subagentEffort?: Effort
+  style?: Style
+}
+
+export function stripJsonc(text: string): string {
+  let result = ''
+  let inString = false
+  let i = 0
+
+  function skipWhitespaceAndComments(start: number): number {
+    let j = start
+    while (j < text.length) {
+      if (/\s/.test(text[j]!)) {
+        j++
+        continue
+      }
+      if (text[j] === '/' && text[j + 1] === '/') {
+        while (j < text.length && text[j] !== '\n') j++
+        if (j < text.length) j++
+        continue
+      }
+      if (text[j] === '/' && text[j + 1] === '*') {
+        j += 2
+        while (j < text.length - 1) {
+          if (text[j] === '*' && text[j + 1] === '/') {
+            j += 2
+            break
+          }
+          j++
+        }
+        continue
+      }
+      break
+    }
+    return j
+  }
+
+  while (i < text.length) {
+    const char = text[i]
+    const next = text[i + 1]
+
+    if (inString) {
+      result += char
+      if (char === '\\' && next) {
+        result += next
+        i += 2
+        continue
+      }
+      if (char === '"') {
+        inString = false
+      }
+      i++
+      continue
+    }
+
+    if (char === '"') {
+      inString = true
+      result += char
+      i++
+      continue
+    }
+
+    if (char === '/' && next === '/') {
+      let j = i
+      while (j < text.length && text[j] !== '\n') j++
+      if (j < text.length) result += '\n'
+      i = j + 1
+      continue
+    }
+
+    if (char === '/' && next === '*') {
+      let j = i + 2
+      while (j < text.length - 1) {
+        if (text[j] === '*' && text[j + 1] === '/') {
+          j += 2
+          break
+        }
+        j++
+      }
+      i = j
+      continue
+    }
+
+    if (char === ',' && !inString) {
+      const j = skipWhitespaceAndComments(i + 1)
+      if (j < text.length && (text[j] === '}' || text[j] === ']')) {
+        i = j
+        continue
+      }
+      result += char
+      i++
+      continue
+    }
+
+    result += char
+    i++
+  }
+
+  return result
+}
+
+function describeJsonError(path: string, error: unknown): Error {
+  const message = error instanceof Error ? error.message : String(error)
+  return new Error(`malformed config at ${path}: ${message}`)
+}
+
+export async function readLayer(path: string): Promise<unknown> {
+  const file = Bun.file(path)
+  if (!(await file.exists())) return {}
+  const text = await file.text()
+  try {
+    return JSON.parse(stripJsonc(text))
+  } catch (error) {
+    throw describeJsonError(path, error)
+  }
+}
+
+function merge(base: Record<string, unknown>, top: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base }
+  for (const [key, value] of Object.entries(top)) {
+    const existing = out[key]
+    const mergedValue =
+      value && typeof value === 'object' && !Array.isArray(value) && existing && typeof existing === 'object'
+        ? merge(existing as Record<string, unknown>, value as Record<string, unknown>)
+        : value
+    Object.defineProperty(out, key, { value: mergedValue, enumerable: true, configurable: true, writable: true })
+  }
+  return out
+}
+
+// `defineProperty` rather than `out[id] = value`: `id` comes from an attacker-controlled JSON
+// key (an agent id in a cloned repo's config), and plain bracket assignment on a plain object
+// triggers the `__proto__` setter instead of creating an own property.
+function setOwn(obj: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(obj, key, { value, enumerable: true, configurable: true, writable: true })
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+// bin, permission and harness decide what konvoy runs and how much it trusts the process it
+// spawns — properties of the machine the person is running konvoy on, not of the repo they
+// cloned. A project layer may not set them at any level they appear; only the global config can.
+const PRIVILEGED_DEFAULTS_KEYS = ['permission', 'harness'] as const
+const PRIVILEGED_AGENT_KEYS = ['bin', 'permission', 'harness'] as const
+// gate names a command konvoy executes automatically after every turn — wider than `bin`,
+// which at least requires the user to already be using that agent. It sits at the top level
+// of the config, not under `defaults` or `agents.<id>`, so it needs its own case here.
+const PRIVILEGED_TOP_LEVEL_KEYS = ['gate'] as const
+
+function warnIgnored(path: string): void {
+  console.error(`konvoy: ignoring project-level "${path}" — privileged, set it in the global config instead`)
+}
+
+function stripProjectPrivileges(layer: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...layer }
+
+  for (const key of PRIVILEGED_TOP_LEVEL_KEYS) {
+    if (key in out) {
+      warnIgnored(key)
+      delete out[key]
+    }
+  }
+
+  if (isPlainObject(out.defaults)) {
+    const cleaned = { ...out.defaults }
+    for (const key of PRIVILEGED_DEFAULTS_KEYS) {
+      if (key in cleaned) {
+        warnIgnored(`defaults.${key}`)
+        delete cleaned[key]
+      }
+    }
+    out.defaults = cleaned
+  }
+
+  if (isPlainObject(out.agents)) {
+    const cleanedAgents: Record<string, unknown> = {}
+    for (const [id, agentCfg] of Object.entries(out.agents)) {
+      if (!isPlainObject(agentCfg)) {
+        setOwn(cleanedAgents, id, agentCfg)
+        continue
+      }
+      const cleaned = { ...agentCfg }
+      for (const key of PRIVILEGED_AGENT_KEYS) {
+        if (key in cleaned) {
+          warnIgnored(`agents.${id}.${key}`)
+          delete cleaned[key]
+        }
+      }
+      setOwn(cleanedAgents, id, cleaned)
+    }
+    out.agents = cleanedAgents
+  }
+
+  return out
+}
+
+// A leading dash is what makes a model string dangerous: spawned with `--model <value>`, it
+// lands as the next argv token with no `--` guard, unlike the prompt. Unlike bin/permission/
+// harness, a project may legitimately pin a model — so this is validated, not merge-source
+// restricted, and applies to whichever layer's value survives the merge.
+// `/` because opencode names models provider/model; `#` stays out because the variant after
+// it is konvoy's own effort dial, appended by the adapter
+const MODEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:\/-]*$/
+
+function stripInvalidModels(layer: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...layer }
+  if (!isPlainObject(out.agents)) return out
+
+  const cleanedAgents: Record<string, unknown> = {}
+  for (const [id, agentCfg] of Object.entries(out.agents)) {
+    if (!isPlainObject(agentCfg)) {
+      setOwn(cleanedAgents, id, agentCfg)
+      continue
+    }
+    const cleaned = { ...agentCfg }
+    if (typeof cleaned.model === 'string' && !MODEL_PATTERN.test(cleaned.model)) {
+      console.error(`konvoy: ignoring invalid agents.${id}.model "${cleaned.model}" — must match ${MODEL_PATTERN}`)
+      delete cleaned.model
+    }
+    setOwn(cleanedAgents, id, cleaned)
+  }
+  out.agents = cleanedAgents
+  return out
+}
+
+// only a leading `~/`, or a bare `~`, is a home-directory reference — a tilde anywhere else
+// in the path (e.g. `rel/~/x`) is left alone
+function expandHome(p: string): string {
+  if (p === '~') return home()
+  if (p.startsWith('~/')) return join(home(), p.slice(2))
+  return p
+}
+
+export async function loadConfig(opts: { cwd: string; globalPath?: string }): Promise<Config> {
+  const globalPath = opts.globalPath ?? globalConfigPath()
+  const globalLayer = (await readLayer(globalPath)) as Record<string, unknown>
+  const projectLayer = stripProjectPrivileges((await readLayer(projectConfigPath(opts.cwd))) as Record<string, unknown>)
+  const merged = stripInvalidModels(merge(globalLayer, projectLayer))
+  const parsed = configSchema.safeParse(merged)
+  if (!parsed.success) {
+    const where = describeIssue(parsed.error.issues[0])
+    // the project layer is the lower-trust one: a repository's mistake is reported and the layer
+    // set aside, so konvoy still runs in that directory; the user's own file stays strict
+    const globalOnly = configSchema.safeParse(stripInvalidModels(merge(globalLayer, {})))
+    if (globalOnly.success) {
+      console.error(`konvoy: ignoring project-level config at ${projectConfigPath(opts.cwd)} — invalid at ${where}`)
+      return finishConfig(globalOnly.data)
+    }
+    throw new Error(`invalid konvoy config at ${where}`)
+  }
+  return finishConfig(parsed.data)
+}
+
+function describeIssue(issue: { path: PropertyKey[]; code: string; message: string; keys?: unknown } | undefined): string {
+  let pathStr = issue?.path.map(String).join('.')
+  const keys = issue?.code === 'unrecognized_keys' ? (issue.keys as string[] | undefined) : undefined
+  if (keys && keys.length > 0) pathStr = [...(issue?.path ?? []).map(String), keys[0]].join('.')
+  return `${pathStr}: ${issue?.message}`
+}
+
+function finishConfig(data: Config): Config {
+  for (const agentCfg of Object.values(data.agents)) {
+    if (agentCfg?.bin) agentCfg.bin = expandHome(agentCfg.bin)
+  }
+  return data
+}
+
+export function resolveAgent(cfg: Config, agent: AgentId): AgentSettings {
+  const a = cfg.agents[agent] ?? {}
+  const ownStyle = a.style
+  const defaultStyle = cfg.defaults.style ?? undefined
+  // an explicit `null` opts an agent out of a `defaults.style`, unlike `effort`/`permission`
+  // where the per-agent value is only ever absent or set — so this can't reuse `??`.
+  const style = ownStyle === null ? undefined : (ownStyle ?? defaultStyle)
+  return {
+    enabled: a.enabled ?? true,
+    model: a.model,
+    effort: a.effort ?? cfg.defaults.effort,
+    permission: a.permission ?? cfg.defaults.permission,
+    harness: a.harness ?? cfg.defaults.harness,
+    bin: a.bin,
+    subagentEffort: a.subagentEffort,
+    style,
+  }
+}
+
+const isAgentId = (value: string): value is AgentId => (agentIds as readonly string[]).includes(value)
+
+// An envelope's `to` is free text a model wrote, not a validated key — trimmed and
+// lower-cased before either check runs, since a model may write "Reviewer" or " claude ".
+// An agent id wins over a role of the same name: a role can be reassigned mid-session, an
+// agent id cannot.
+export function resolveRecipient(cfg: Config, to: string): AgentId | null {
+  const norm = to.trim().toLowerCase()
+  if (isAgentId(norm)) return norm
+  if (norm === 'lead' || norm === 'implementer' || norm === 'reviewer' || norm === 'researcher') {
+    return cfg.roles[norm] ?? null
+  }
+  return null
+}
+
+export function explain(
+  cfg: Config,
+  agent: AgentId,
+  key: 'effort' | 'permission' | 'model',
+): { value: string | undefined; source: 'agent' | 'defaults' | 'built-in' } {
+  const a = cfg.agents[agent] ?? {}
+  if (a[key] !== undefined) return { value: a[key], source: 'agent' }
+  if (key === 'model') return { value: undefined, source: 'built-in' }
+  return { value: cfg.defaults[key], source: 'defaults' }
+}

package/src/config/schema.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod'
+
+export const agentIds = ['claude', 'codex', 'kiro', 'opencode'] as const
+export const effortSchema = z.enum(['low', 'medium', 'high', 'max'])
+export const permissionSchema = z.enum(['safe', 'edit', 'yolo'])
+export const harnessSchema = z.enum(['minimal', 'inherit'])
+export const agentIdSchema = z.enum(agentIds)
+// konvoy's own instruction, not a model capability — `.nullish()` so a per-agent `null` can
+// opt out of a `defaults.style` of 'brief', which a plain `.optional()` cannot express.
+export const styleSchema = z.enum(['brief'])
+
+const agentConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    model: z.string().optional(),
+    effort: effortSchema.optional(),
+    permission: permissionSchema.optional(),
+    harness: harnessSchema.optional(),
+    bin: z.string().optional(),
+    subagentEffort: effortSchema.optional(),
+    engine: z.string().optional(),
+    style: styleSchema.nullish(),
+  })
+  .strict()
+
+const defaultsObjectSchema = z
+  .object({
+    effort: effortSchema.default('high'),
+    permission: permissionSchema.default('edit'),
+    harness: harnessSchema.default('minimal'),
+    style: styleSchema.nullish(),
+  })
+  .strict()
+
+const rolesObjectSchema = z
+  .object({
+    lead: agentIdSchema.optional(),
+    implementer: agentIdSchema.optional(),
+    reviewer: agentIdSchema.optional(),
+    researcher: agentIdSchema.optional(),
+  })
+  .strict()
+
+const MAX_TURN_TIMEOUT_SEC = 24 * 60 * 60
+
+const policyObjectSchema = z
+  .object({
+    maxDelegationDepth: z.number().int().positive().default(3),
+    // A project config sets this, so it is clamped rather than trusted outright — otherwise a
+    // hostile repo could make konvoy wait forever on every turn.
+    turnTimeoutSec: z
+      .number()
+      .int()
+      .positive()
+      .default(900)
+      .transform((v) => Math.min(v, MAX_TURN_TIMEOUT_SEC)),
+    isolation: z.enum(['serial', 'parallel']).default('serial'),
+  })
+  .strict()
+
+// An empty chain means the feature is off, which is the default. A project layer may set
+// this: naming an ordering among agents the user already enabled grants nothing new, unlike
+// `bin` or `permission`.
+const failoverObjectSchema = z
+  .object({
+    chain: z.array(agentIdSchema).default([]),
+    upstreamRetries: z.number().int().min(0).max(10).default(3),
+  })
+  .strict()
+
+export const configSchema = z
+  .object({
+    defaults: defaultsObjectSchema.prefault({}),
+    agents: z.partialRecord(agentIdSchema, agentConfigSchema).default({}),
+    roles: rolesObjectSchema.prefault({}),
+    policy: policyObjectSchema.prefault({}),
+    // The command konvoy runs after a turn to produce a pass/fail verdict on the work — a
+    // project layer may never set this; see stripProjectPrivileges in config/load.ts.
+    gate: z.object({ command: z.string().nullish() }).strict().prefault({}),
+    failover: failoverObjectSchema.prefault({}),
+    // Off by default: a single-agent session has no handoff to describe, and asking for one
+    // anyway would cost output tokens on every turn for a format nobody reads.
+    delegation: z.object({ enabled: z.boolean().default(false) }).strict().prefault({}),
+    pricing: z
+      .object({
+        asOf: z.string().default(''),
+        models: z.record(z.string(), z.object({ inputPerMTok: z.number(), outputPerMTok: z.number() }).strict()).default({}),
+        credits: z.record(z.string(), z.object({ usdPerCredit: z.number() }).strict()).default({}),
+      })
+      .strict()
+      .prefault({}),
+  })
+  .strict()
+
+export type Config = z.infer<typeof configSchema>
+export type AgentId = z.infer<typeof agentIdSchema>
+export type Effort = z.infer<typeof effortSchema>
+export type Permission = z.infer<typeof permissionSchema>
+export type Harness = z.infer<typeof harnessSchema>
+export type Style = z.infer<typeof styleSchema>

package/src/core/children.ts

@@ -0,0 +1,62 @@
+type Child = { kill(): void; exitCode: number | null }
+
+const live = new Set<Child>()
+let installed = false
+
+function install(): void {
+  if (installed) return
+  installed = true
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+    process.on(signal, () => {
+      for (const child of live) {
+        if (child.exitCode === null) child.kill()
+      }
+      live.clear()
+      for (const handler of exitHandlers) {
+        try {
+          handler(signal)
+        } catch {
+          // a cleanup that fails must not stop the others from running
+        }
+      }
+      exitHandlers.clear()
+      process.exit(signal === 'SIGINT' ? 130 : 143)
+    })
+  }
+}
+
+type ExitHandler = (signal: 'SIGINT' | 'SIGTERM') => void
+
+const exitHandlers = new Set<ExitHandler>()
+
+export function onExit(fn: ExitHandler): () => void {
+  install()
+  exitHandlers.add(fn)
+  return () => exitHandlers.delete(fn)
+}
+
+export function track(child: Child): void {
+  install()
+  live.add(child)
+}
+
+export function untrack(child: Child): void {
+  live.delete(child)
+}
+
+export function liveCount(): number {
+  return live.size
+}
+
+// Bun's own `timeout` sends killSignal once and never follows up — a child that traps or
+// ignores SIGTERM then hangs forever. SIGKILL cannot be trapped; it goes out once the timeout
+// has had a grace period to work. Every bounded spawn (a turn, a gate) uses this one.
+export const DEFAULT_KILL_GRACE_MS = 2_000
+
+export function escalateKill(proc: { exitCode: number | null; kill(signal: 'SIGKILL'): void }, afterMs: number): () => void {
+  const timer = setTimeout(() => {
+    if (proc.exitCode === null) proc.kill('SIGKILL')
+  }, afterMs)
+  timer.unref?.()
+  return () => clearTimeout(timer)
+}