@lythos/agent-adapter 0.17.11 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/agent-adapter",
-  "version": "0.17.11",
+  "version": "0.19.0",
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",

package/src/adapters/kimi.test.ts

@@ -1,5 +1,14 @@
 import { describe, expect, it } from 'bun:test'
-import { detectKimiBinary, buildKimiCommand, parseKimiStreamJson } from './kimi'
+import {
+  detectKimiBinary,
+  buildKimiCommand,
+  parseKimiStreamJson,
+  parseKimiVersion,
+  classifyKimiUpstream,
+  satisfiesVersionRange,
+  detectKimiProtocolMismatch,
+  KIMI_VERSION_RANGE,
+} from './kimi'
 
 describe('detectKimiBinary', () => {
   it('returns a non-empty string when a kimi binary is available', () => {
@@ -19,12 +28,18 @@ describe('buildKimiCommand', () => {
     expect(cmd).toContain('stream-json')
   })
 
-  it('builds kimi CLI args for kimi binary', () => {
-    const cmd = buildKimiCommand(undefined, 'kimi')
+  it('builds kimi-code args for kimi binary (never --print)', () => {
+    const cmd = buildKimiCommand(undefined, 'kimi', 'kimi-code', 'do the thing')
     expect(cmd[0]).toBe('kimi')
-    expect(cmd).toContain('--print')
+    expect(cmd).toContain('--prompt')
+    expect(cmd).toContain('do the thing')
     expect(cmd).toContain('--output-format')
     expect(cmd).toContain('stream-json')
+    expect(cmd).not.toContain('--print')
+  })
+
+  it('kimi-code requires a prompt argument', () => {
+    expect(() => buildKimiCommand(undefined, 'kimi', 'kimi-code')).toThrow('--prompt')
   })
 
   it('does not use shell or redirect (injection-safe)', () => {
@@ -116,3 +131,112 @@ describe('parseKimiStreamJson', () => {
     expect(result.checkpoints[1].stdout_summary).toBe('agent-stdout.txt\nreport.docx')
   })
 })
+
+describe('parseKimiVersion', () => {
+  it('parses kimi-code bare version output', () => {
+    expect(parseKimiVersion('0.38.0')).toEqual({ version: '0.38.0', major: 0 })
+  })
+
+  it('parses kimi-cli self-report ("kimi, version 1.45.0")', () => {
+    expect(parseKimiVersion('kimi, version 1.45.0')).toEqual({ version: '1.45.0', major: 1 })
+  })
+
+  it('returns null for unparseable output', () => {
+    expect(parseKimiVersion('garbage')).toBeNull()
+    expect(parseKimiVersion('')).toBeNull()
+  })
+})
+
+describe('classifyKimiUpstream', () => {
+  it('major 0 → kimi-code', () => {
+    expect(classifyKimiUpstream(0)).toBe('kimi-code')
+  })
+
+  it('major 1 → kimi-cli', () => {
+    expect(classifyKimiUpstream(1)).toBe('kimi-cli')
+  })
+
+  it('unknown majors fail closed', () => {
+    expect(classifyKimiUpstream(2)).toBeNull()
+    expect(classifyKimiUpstream(9)).toBeNull()
+  })
+})
+
+describe('satisfiesVersionRange', () => {
+  it('accepts in-range kimi-code and kimi-cli versions', () => {
+    expect(satisfiesVersionRange('0.38.0', KIMI_VERSION_RANGE)).toBe(true)
+    expect(satisfiesVersionRange('1.45.0', KIMI_VERSION_RANGE)).toBe(true)
+  })
+
+  it('rejects out-of-range versions', () => {
+    expect(satisfiesVersionRange('2.0.0', KIMI_VERSION_RANGE)).toBe(false)
+    expect(satisfiesVersionRange('0.10.0', KIMI_VERSION_RANGE)).toBe(false)
+    expect(satisfiesVersionRange('9.9.9', KIMI_VERSION_RANGE)).toBe(false)
+  })
+
+  it('boundary values follow comparator semantics', () => {
+    expect(satisfiesVersionRange('0.30.0', KIMI_VERSION_RANGE)).toBe(true)  // >= inclusive
+    expect(satisfiesVersionRange('2.0.0', '>=0.30.0 <2.0.0')).toBe(false)  // < exclusive
+    expect(satisfiesVersionRange('1.0.0', '>1.0.0')).toBe(false)
+    expect(satisfiesVersionRange('1.0.1', '>1.0.0')).toBe(true)
+    expect(satisfiesVersionRange('1.0.0', '<=1.0.0')).toBe(true)
+  })
+})
+
+describe('parseKimiStreamJson — real kimi-code capture', () => {
+  // Live capture from kimi-code 0.38.0: `kimi -p "Reply with exactly: PROBE_OK" --output-format stream-json`
+  const kimiCodeCapture = [
+    '{"role":"meta","type":"system.version","version":"0.38.0"}',
+    '{"role":"assistant","content":"PROBE_OK"}',
+    '{"role":"meta","type":"session.resume_hint","session_id":"session_x","command":"kimi -r session_x","content":"To resume this session: kimi -r session_x"}',
+  ].join('\n')
+
+  it('extracts assistant text and skips meta events', () => {
+    const result = parseKimiStreamJson(kimiCodeCapture)
+    expect(result.text).toBe('PROBE_OK')
+    expect(result.events).toBe(3)
+    expect(result.checkpoints).toEqual([])
+  })
+})
+
+describe('detectKimiProtocolMismatch', () => {
+  it('regression: kimi-code invoked with --print must NOT pass silently (the live bug)', () => {
+    // Exact live capture: `kimi --print --output-format stream-json` → exit 1, empty stdout
+    const msg = detectKimiProtocolMismatch({
+      code: 1,
+      rawStdout: '',
+      stderr: "error: unknown option '--print'\n(Did you mean --prompt?)",
+      events: 0,
+    })
+    expect(msg).not.toBeNull()
+    expect(msg).toContain('code 1')
+    expect(msg).toContain("unknown option '--print'")
+  })
+
+  it('exit 0 with non-JSON stdout → protocol mismatch', () => {
+    const msg = detectKimiProtocolMismatch({
+      code: 0,
+      rawStdout: 'plain text that is not stream-json',
+      stderr: '',
+      events: 0,
+    })
+    expect(msg).not.toBeNull()
+    expect(msg).toContain('no parseable stream-json events')
+  })
+
+  it('exit 0 with empty stdout → no-output error', () => {
+    const msg = detectKimiProtocolMismatch({ code: 0, rawStdout: '', stderr: '', events: 0 })
+    expect(msg).not.toBeNull()
+    expect(msg).toContain('no output at all')
+  })
+
+  it('exit 0 with parsed events → OK', () => {
+    const msg = detectKimiProtocolMismatch({
+      code: 0,
+      rawStdout: '{"role":"assistant","content":"hi"}',
+      stderr: '',
+      events: 1,
+    })
+    expect(msg).toBeNull()
+  })
+})

package/src/adapters/kimi.ts

@@ -7,28 +7,80 @@ import { registerAgent } from '../registry'
 
 // ── Pure functions (testable without CLI) ────────────────────────────────────
 
-/** Detect which kimi binary to use. Prefers kimi-cli (legacy, v1.x) over kimi (kimi-code, v0.5+). */
-export function detectKimiBinary(): string {
-  // kimi-cli v1.x supports --print --output-format stream-json
-  // kimi v0.5.0 (kimi-code) does NOT support --print; it uses --prompt with different semantics
-  if (Bun.which('kimi-cli')) {
-    return 'kimi-cli'
-  }
-  if (Bun.which('kimi')) {
-    return 'kimi'
+/** kimi-cli = legacy Python CLI (v1.x, binary `kimi-cli`); kimi-code = TS CLI (v0.x, binary `kimi`). */
+export type KimiUpstream = 'kimi-cli' | 'kimi-code'
+
+/** Supported range across both upstreams (ADR-20260828004129233 Option B). */
+export const KIMI_VERSION_RANGE = '>=0.30.0 <2.0.0'
+
+/** Detect which kimi binary to use, in the declared preference order (default: kimi-cli legacy over kimi kimi-code). */
+export function detectKimiBinary(binaries: string[] = ['kimi-cli', 'kimi']): string {
+  for (const b of binaries) {
+    if (Bun.which(b)) return b
   }
   return ''
 }
 
-/** Build kimi CLI command args (no shell wrapper — safe from injection). */
+/**
+ * Parse the first semver triple from `<binary> --version` output.
+ * Both upstreams self-report as "kimi" — kimi-code prints "0.38.0",
+ * kimi-cli prints "kimi, version 1.45.0" — so discriminate on the
+ * version, never on the product name.
+ */
+export function parseKimiVersion(output: string): { version: string; major: number } | null {
+  const m = output.match(/(\d+)\.(\d+)\.(\d+)/)
+  if (!m) return null
+  return { version: m[0], major: parseInt(m[1], 10) }
+}
+
+/** major 0 = kimi-code, major 1 = kimi-cli, anything else = unknown (fail closed). */
+export function classifyKimiUpstream(major: number): KimiUpstream | null {
+  if (major === 0) return 'kimi-code'
+  if (major === 1) return 'kimi-cli'
+  return null
+}
+
+/** Minimal semver-triple check against space-separated comparators (>=, >, <=, <). No semver dep. */
+export function satisfiesVersionRange(version: string, range: string): boolean {
+  const v = version.split('.').map(n => parseInt(n, 10))
+  for (const cmp of range.trim().split(/\s+/)) {
+    const m = cmp.match(/^(>=|<=|>|<)(\d+\.\d+\.\d+)$/)
+    if (!m) return false
+    const t = m[2].split('.').map(n => parseInt(n, 10))
+    let d = 0
+    for (let i = 0; i < 3; i++) {
+      d = (v[i] ?? 0) - (t[i] ?? 0)
+      if (d !== 0) break
+    }
+    if (m[1] === '>=' && d < 0) return false
+    if (m[1] === '>' && d <= 0) return false
+    if (m[1] === '<=' && d > 0) return false
+    if (m[1] === '<' && d >= 0) return false
+  }
+  return true
+}
+
+/**
+ * Build kimi CLI command args (no shell wrapper — safe from injection).
+ * kimi-cli speaks `--print` (prompt on stdin). kimi-code speaks `--prompt <prompt>`
+ * (its `--output-format` only works in prompt mode; `--print` never existed and
+ * exits 1 with "unknown option").
+ */
 export function buildKimiCommand(
   _modelTier?: 'fast' | 'balanced' | 'deep',
   binary = detectKimiBinary(),
+  upstream: KimiUpstream = 'kimi-cli',
+  prompt?: string,
 ): string[] {
   if (!binary) {
     throw new Error('No kimi binary found in PATH. Install: https://github.com/MoonshotAI/kimi-cli')
   }
-  // Both kimi-cli and kimi (if it ever gains --print support) use the same flag set
+  if (upstream === 'kimi-code') {
+    if (!prompt) {
+      throw new Error('kimi-code requires the prompt as a --prompt argument (no stdin prompt mode)')
+    }
+    return [binary, '--prompt', prompt, '--output-format', 'stream-json']
+  }
   return [binary, '--print', '--output-format', 'stream-json']
 }
 
@@ -36,16 +88,20 @@ export function buildKimiCommand(
  * Parse kimi stream-json output into plain text + checkpoint trace.
  * Each line is a JSON event; extracts text from assistant role messages
  * and tool_calls/tool messages into CheckpointEntry for white-box replay.
+ * `events` counts successfully parsed JSON lines — zero events on non-empty
+ * stdout means the upstream is speaking a different protocol.
  */
-export function parseKimiStreamJson(raw: string): { text: string; checkpoints: CheckpointEntry[] } {
+export function parseKimiStreamJson(raw: string): { text: string; checkpoints: CheckpointEntry[]; events: number } {
   const textLines: string[] = []
   const checkpoints: CheckpointEntry[] = []
   const pendingTools = new Map<string, { name: string; args: string }>()
+  let events = 0
 
   for (const line of raw.split('\n')) {
     if (!line.trim()) continue
     try {
       const event = JSON.parse(line)
+      events++
       if (event.role === 'assistant') {
         const content = event.content
         if (typeof content === 'string') {
@@ -85,24 +141,103 @@ export function parseKimiStreamJson(raw: string): { text: string; checkpoints: C
     } catch { /* skip malformed lines */ }
   }
 
-  return { text: textLines.join('\n'), checkpoints }
+  return { text: textLines.join('\n'), checkpoints, events }
+}
+
+/**
+ * Fail-loud check on a finished kimi run. Returns a HATEOAS-style error
+ * message, or null when the run produced parseable stream-json output.
+ * Replaces the old never-throw passthrough that returned empty stdout as success.
+ */
+export function detectKimiProtocolMismatch(result: {
+  code: number
+  rawStdout: string
+  stderr: string
+  events: number
+}): string | null {
+  const { code, rawStdout, stderr, events } = result
+  if (code !== 0) {
+    return [
+      `kimi exited with code ${code} and produced no usable stream-json output.`,
+      stderr.trim() ? `stderr: ${stderr.trim().slice(0, 200)}` : '',
+      `Likely cause: flag/protocol mismatch between this adapter and the installed kimi upstream.`,
+      `Fix: upgrade kimi-cli (https://github.com/MoonshotAI/kimi-cli) or kimi-code, or pick another --player.`,
+    ].filter(Boolean).join('\n   ')
+  }
+  if (!rawStdout.trim()) {
+    return [
+      `kimi exited 0 but produced no output at all.`,
+      `Likely cause: protocol mismatch with the installed kimi upstream.`,
+      `Fix: upgrade kimi-cli/kimi-code, or pick another --player.`,
+    ].join('\n   ')
+  }
+  if (events === 0) {
+    return [
+      `kimi exited 0 but stdout had no parseable stream-json events.`,
+      `stdout (first 200 chars): ${rawStdout.trim().slice(0, 200)}`,
+      `Likely cause: the upstream is speaking a different output protocol.`,
+      `Fix: upgrade kimi-cli/kimi-code, or pick another --player.`,
+    ].join('\n   ')
+  }
+  return null
 }
 
 // ── Spawn wrapper (IO, tested via BDD / arena integration) ──────────────────
 
-async function spawnKimi(opts: {
-  brief: string
-  cwd: string
-  timeoutMs?: number
-}): Promise<AgentRunResult> {
-  const promptFile = join(tmpdir(), `kimi-prompt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.txt`)
-  writeFileSync(promptFile, opts.brief, 'utf-8')
+/** Probe `<binary> <probeArgs>`, classify the upstream, enforce the declared version range. Fail closed. */
+function probeKimiUpstream(
+  binary: string,
+  probeArgs: string[],
+  versionRange: string,
+): { upstream: KimiUpstream; version: string } {
+  const probe = Bun.spawnSync([binary, ...probeArgs])
+  const output = `${probe.stdout.toString()}\n${probe.stderr.toString()}`.trim()
+  const parsed = parseKimiVersion(output)
+  const upstream = parsed ? classifyKimiUpstream(parsed.major) : null
+  if (!parsed || !upstream || !satisfiesVersionRange(parsed.version, versionRange)) {
+    throw new Error([
+      `kimi upstream probe failed: "${binary} ${probeArgs.join(' ')}" returned "${output.slice(0, 120) || '(no output)'}"`,
+      `Detected: ${parsed ? `version ${parsed.version}` : 'unparseable version output'}`,
+      `Supported: kimi-cli 1.x (legacy) / kimi-code 0.x — declared range: ${versionRange}`,
+      `Fix: install/upgrade kimi-cli (https://github.com/MoonshotAI/kimi-cli) or kimi-code, or pick another --player.`,
+    ].join('\n   '))
+  }
+  return { upstream, version: parsed.version }
+}
+
+async function spawnKimi(
+  opts: {
+    brief: string
+    cwd: string
+    timeoutMs?: number
+  },
+  declared?: AgentAdapter['upstream'],
+): Promise<AgentRunResult> {
+  const binary = detectKimiBinary(declared?.binaries)
+  if (!binary) {
+    throw new Error('kimi not found in PATH. Install: https://github.com/MoonshotAI/kimi-cli')
+  }
+  // Contract semantics: adapters without an `upstream` declaration stay unprobed (legacy behavior).
+  const probed = declared ? probeKimiUpstream(binary, declared.probeArgs, declared.versionRange) : null
+  const upstream: KimiUpstream = probed?.upstream ?? 'kimi-cli'
+  if (probed) console.error(`ℹ️  kimi upstream: ${probed.upstream} ${probed.version}`)
+
+  // kimi-cli reads the prompt from stdin (temp file); kimi-code takes it as --prompt argv.
+  let promptFile: string | null = null
+  let cmd: string[]
+  if (upstream === 'kimi-code') {
+    cmd = buildKimiCommand(undefined, binary, upstream, opts.brief)
+  } else {
+    promptFile = join(tmpdir(), `kimi-prompt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.txt`)
+    writeFileSync(promptFile, opts.brief, 'utf-8')
+    cmd = buildKimiCommand(undefined, binary, upstream)
+  }
 
   const start = Date.now()
 
-  const proc = Bun.spawn(buildKimiCommand(), {
+  const proc = Bun.spawn(cmd, {
     cwd: opts.cwd,
-    stdin: Bun.file(promptFile),
+    stdin: promptFile ? Bun.file(promptFile) : 'ignore',
     stdout: 'pipe',
     stderr: 'pipe',
   })
@@ -111,22 +246,20 @@ async function spawnKimi(opts: {
   await proc.exited
   clearTimeout(timeout)
 
-  try { unlinkSync(promptFile) } catch {}
+  if (promptFile) {
+    try { unlinkSync(promptFile) } catch {}
+  }
 
   const durationMs = Date.now() - start
   const rawStdout = await new Response(proc.stdout).text()
   const stderr = await new Response(proc.stderr).text()
   const code = proc.exitCode ?? 1
 
-  let text: string
-  let streamCheckpoints: CheckpointEntry[]
-  try {
-    const parsed = parseKimiStreamJson(rawStdout)
-    text = parsed.text
-    streamCheckpoints = parsed.checkpoints
-  } catch {
-    text = rawStdout
-    streamCheckpoints = []
+  // parseKimiStreamJson never throws; protocol mismatch is detected explicitly.
+  const parsed = parseKimiStreamJson(rawStdout)
+  const mismatch = detectKimiProtocolMismatch({ code, rawStdout, stderr, events: parsed.events })
+  if (mismatch) {
+    throw new Error(mismatch)
   }
 
   // Preserve raw JSONL for post-hoc white-box analysis
@@ -135,20 +268,22 @@ async function spawnKimi(opts: {
   } catch { /* ignore write failures */ }
 
   const fileCheckpoints = readCheckpoints(opts.cwd)
-  const checkpoints = [...streamCheckpoints, ...fileCheckpoints]
+  const checkpoints = [...parsed.checkpoints, ...fileCheckpoints]
 
-  return { stdout: text.trim(), stderr, code, durationMs, checkpoints }
+  return { stdout: parsed.text.trim(), stderr, code, durationMs, checkpoints }
 }
 
 const kimiAdapter: AgentAdapter = {
   name: 'kimi',
 
+  upstream: {
+    binaries: ['kimi-cli', 'kimi'],
+    versionRange: KIMI_VERSION_RANGE,
+    probeArgs: ['--version'],
+  },
+
   async spawn(opts): Promise<AgentRunResult> {
-    const binary = detectKimiBinary()
-    if (!binary) {
-      throw new Error('kimi not found in PATH. Install: https://github.com/MoonshotAI/kimi-cli')
-    }
-    return spawnKimi(opts)
+    return spawnKimi(opts, kimiAdapter.upstream)
   },
 
   async invokeTool(_opts): Promise<unknown> {

package/src/index.ts

@@ -37,6 +37,9 @@ export { readCheckpoints } from './checkpoint'
 // Built-in adapters — lightweight CLI wrappers only.
 // Heavy adapters live in separate packages (see above).
 export { kimiAdapter } from './adapters/kimi'
+// Shared version-range check (ADR-20260828004129233 Option B) — used by adapter
+// packages (e.g. agent-adapter-deepseek-harness) that declare an upstream range.
+export { satisfiesVersionRange } from './adapters/kimi'
 export {
   claudeCliAdapter,
   buildClaudeCommand,

package/src/types.ts

@@ -33,6 +33,22 @@ export interface ToolDefinition {
 
 export interface AgentAdapter {
   name: string
+
+  /**
+   * Optional upstream declaration (ADR-20260828004129233 Option B): which upstream
+   * binary(-ies) this adapter drives, the supported version range, and how to probe.
+   * Adapters that declare it probe at spawn time and fail closed (loud HATEOAS error)
+   * on unknown/out-of-range upstreams. Adapters without it are unprobed (unchanged).
+   */
+  upstream?: {
+    /** Candidate binary names in preference order (e.g. ['kimi-cli', 'kimi']). */
+    binaries: string[]
+    /** Space-separated comparators, e.g. '>=0.30.0 <2.0.0'. */
+    versionRange: string
+    /** Args that print the version, e.g. ['--version']. */
+    probeArgs: string[]
+  }
+
   spawn(opts: {
     cwd: string
     brief: string