@plimeor/harness 0.1.0

package/src/adapters/index.ts

@@ -0,0 +1,9 @@
+import './claude'
+import './codex'
+import './kiro'
+import './pi'
+
+export { claudeAdapter } from './claude'
+export { codexAdapter } from './codex'
+export { kiroAdapter } from './kiro'
+export { piAdapter } from './pi'

package/src/adapters/kiro.ts

@@ -0,0 +1,57 @@
+import { harness } from '../registry'
+import type { HarnessContext, RunOutputRequest, RunRequest, TextOutputRequest } from '../types'
+import { configDirectory, createExtensionFacet } from './extensions'
+import { createBuiltInAdapter, planTextCommand, unsupportedOutputMode } from './shared'
+
+const HARNESS_ID = 'kiro'
+
+export const kiroAdapter = createBuiltInAdapter({
+  commands: ['kiro-cli'],
+  id: HARNESS_ID,
+  identity: /kiro/i,
+  installHint: 'Install Kiro CLI and ensure `kiro-cli --version` is available on PATH.',
+  extensions(context: HarnessContext | undefined) {
+    const directory = context?.env?.KIRO_HOME ?? configDirectory(context?.home, '.kiro')
+    return createExtensionFacet({
+      configDirectory: directory,
+      context,
+      harnessId: HARNESS_ID,
+      mcp: { configFile: `${directory}/settings/mcp.json`, kind: 'kiro-cli' },
+      skillsDirectory: `${directory}/skills`,
+      hooks: {
+        hooksDirectory: `${directory}/hooks`,
+        kind: 'kiro-hook-files',
+        events: [
+          'Manual',
+          'PostFileCreate',
+          'PostFileDelete',
+          'PostFileSave',
+          'PostTaskExec',
+          'PostToolUse',
+          'PreTaskExec',
+          'PreToolUse',
+          'SessionStart',
+          'Stop',
+          'UserPromptSubmit'
+        ]
+      }
+    })
+  },
+  plan(request: RunRequest<RunOutputRequest>, command: string, cwd: string) {
+    const output = request.output ?? ({ mode: 'text' } satisfies TextOutputRequest)
+    if (!output.mode || output.mode === 'text') {
+      return planTextCommand({
+        args: ['chat', '--no-interactive', '--wrap', 'never', request.prompt],
+        command,
+        cwd,
+        harnessId: HARNESS_ID,
+        output: { mode: 'text' },
+        request
+      })
+    }
+
+    return unsupportedOutputMode(HARNESS_ID, output)
+  }
+})
+
+harness.use(kiroAdapter)

package/src/adapters/pi.ts

@@ -0,0 +1,65 @@
+import { harness } from '../registry'
+import type { HarnessContext, JsonlOutputRequest, RunOutputRequest, RunRequest, TextOutputRequest } from '../types'
+import { configDirectory, createExtensionFacet } from './extensions'
+import { createBuiltInAdapter, planCommand, shellQuote, unsupportedOutputMode } from './shared'
+
+const HARNESS_ID = 'pi'
+
+export const piAdapter = createBuiltInAdapter({
+  commands: ['pi'],
+  id: HARNESS_ID,
+  identity: /^\d+\.\d+\.\d+/,
+  installHint: 'Install pi and ensure `pi --version` is available on PATH.',
+  extensions(context: HarnessContext | undefined) {
+    const directory = configDirectory(context?.home, '.pi/agent')
+    return createExtensionFacet({
+      configDirectory: directory,
+      context,
+      harnessId: HARNESS_ID,
+      skillsDirectory: `${directory}/skills`
+    })
+  },
+  plan(request: RunRequest<RunOutputRequest>, command: string, cwd: string) {
+    const output = request.output ?? ({ mode: 'text' } satisfies TextOutputRequest)
+    if (output.mode === 'jsonl') {
+      return planCommand({
+        args: ['-lc', piCommand(command, request.prompt, 'json')],
+        command: 'fish',
+        cwd,
+        harnessId: HARNESS_ID,
+        output: output satisfies JsonlOutputRequest,
+        request
+      })
+    }
+
+    if (!output.mode || output.mode === 'text') {
+      return planCommand({
+        args: ['-lc', piCommand(command, request.prompt, 'text')],
+        command: 'fish',
+        cwd,
+        harnessId: HARNESS_ID,
+        output: { mode: 'text' },
+        request
+      })
+    }
+
+    return unsupportedOutputMode(HARNESS_ID, output)
+  }
+})
+
+harness.use(piAdapter)
+
+function piCommand(command: string, prompt: string, mode: 'json' | 'text'): string {
+  return [
+    shellQuote(command),
+    '-p',
+    '--no-session',
+    '--no-tools',
+    '--no-extensions',
+    '--no-skills',
+    '--no-context-files',
+    '--mode',
+    mode,
+    shellQuote(prompt)
+  ].join(' ')
+}

package/src/adapters/shared.ts

@@ -0,0 +1,338 @@
+import { access } from 'node:fs/promises'
+import { delimiter, join } from 'node:path'
+
+import { HarnessPlanError } from '../errors'
+import { createProcessRunner } from '../process'
+import type {
+  CommandPlan,
+  ExtensionFacet,
+  HarnessAdapter,
+  HarnessContext,
+  HarnessDetection,
+  HarnessHandle,
+  HarnessId,
+  HarnessRun,
+  HealthReport,
+  JsonlOutputRequest,
+  ProcessFacet,
+  RunOutputRequest,
+  RunRequest,
+  StructuredOutputRequest,
+  TextOutputRequest
+} from '../types'
+
+type BuiltInAdapterConfig = {
+  id: Extract<HarnessId, 'claude' | 'codex' | 'kiro' | 'pi'>
+  commands: string[]
+  identity: RegExp
+  identityArgs?: string[]
+  installHint: string
+  requiresGoogleAccessBeforeSmoke?: boolean
+  extensions(context: HarnessContext | undefined): ExtensionFacet
+  plan(request: RunRequest<RunOutputRequest>, command: string, cwd: string): CommandPlan<RunOutputRequest>
+}
+
+const HEALTH_PROMPT_TIMEOUT_MS = 30_000
+const GOOGLE_ACCESS_TIMEOUT_MS = 5_000
+const GOOGLE_ACCESS_URL = 'https://www.google.com/generate_204'
+
+export function createBuiltInAdapter(config: BuiltInAdapterConfig): HarnessAdapter {
+  return {
+    id: config.id,
+    async detect(context?: HarnessContext): Promise<HarnessDetection> {
+      return detectCommand(config, context)
+    },
+
+    async open(context?: HarnessContext): Promise<HarnessHandle> {
+      const detection = await detectCommand(config, context)
+      const runner = createProcessRunner(config.id)
+      const process: ProcessFacet = {
+        async plan<Output extends RunOutputRequest = TextOutputRequest>(
+          request: RunRequest<Output>
+        ): Promise<CommandPlan<Output>> {
+          if (!detection.detected || !detection.binary) {
+            throw new HarnessPlanError({
+              harnessId: config.id,
+              kind: 'unsupported_operation',
+              message: `${config.id} CLI is not installed or was not recognized.`
+            })
+          }
+
+          return config.plan(request, detection.binary.command, resolveCwd(context)) as CommandPlan<Output>
+        },
+        async run<Output extends RunOutputRequest = TextOutputRequest>(
+          input: RunRequest<Output> | CommandPlan<Output>
+        ): Promise<HarnessRun<Output>> {
+          if (isCommandPlan(input)) {
+            return runner.run(input)
+          }
+
+          const plan = await process.plan(input)
+          return runner.run(plan)
+        }
+      }
+
+      return {
+        detection,
+        extensions: config.extensions(context),
+        health: {
+          async check(): Promise<HealthReport> {
+            if (!detection.detected || !detection.binary) {
+              return {
+                message: `${config.id} CLI is not installed or was not recognized. ${config.installHint}`,
+                success: false
+              }
+            }
+
+            if (config.requiresGoogleAccessBeforeSmoke) {
+              const googleAccess = await checkGoogleAccess(config.id)
+              if (!googleAccess.success) {
+                return googleAccess
+              }
+            }
+
+            const plan = config.plan(
+              {
+                output: { mode: 'text' },
+                prompt: 'Reply with OK.',
+                timeoutMs: HEALTH_PROMPT_TIMEOUT_MS
+              },
+              detection.binary.command,
+              resolveCwd(context)
+            )
+
+            try {
+              const run = await runner.run(plan)
+              const result = await run.result
+              if (result.finalText.trim().length > 0) {
+                return { success: true }
+              }
+
+              return {
+                message: `${config.id} CLI did not produce output for the health prompt within ${HEALTH_PROMPT_TIMEOUT_MS}ms.`,
+                success: false
+              }
+            } catch (error) {
+              return {
+                message: `${config.id} CLI did not respond to the health prompt within ${HEALTH_PROMPT_TIMEOUT_MS}ms: ${formatError(error)}`,
+                success: false
+              }
+            }
+          }
+        },
+        process
+      }
+    }
+  }
+}
+
+async function checkGoogleAccess(harnessId: HarnessId): Promise<HealthReport> {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => {
+    controller.abort()
+  }, GOOGLE_ACCESS_TIMEOUT_MS)
+
+  try {
+    const response = await fetch(GOOGLE_ACCESS_URL, {
+      method: 'GET',
+      signal: controller.signal
+    })
+
+    if (response.ok) {
+      return { success: true }
+    }
+
+    return {
+      message: `${harnessId} CLI smoke prompt was skipped because google.com is not reachable. ${GOOGLE_ACCESS_URL} returned HTTP ${response.status}. Check local network access to google.com.`,
+      success: false
+    }
+  } catch (error) {
+    return {
+      message: `${harnessId} CLI smoke prompt was skipped because google.com is not reachable within ${GOOGLE_ACCESS_TIMEOUT_MS}ms. Check local network access to google.com: ${formatError(error)}`,
+      success: false
+    }
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+function isCommandPlan<Output extends RunOutputRequest>(
+  input: RunRequest<Output> | CommandPlan<Output>
+): input is CommandPlan<Output> {
+  return 'args' in input && 'command' in input && 'harnessId' in input
+}
+
+export function unsupportedOutputMode(harnessId: HarnessId, output: RunOutputRequest): never {
+  throw new HarnessPlanError({
+    harnessId,
+    kind: 'unsupported_output_mode',
+    message: unsupportedOutputModeMessage(harnessId, output)
+  })
+}
+
+function unsupportedOutputModeMessage(harnessId: HarnessId, output: RunOutputRequest): string {
+  const mode = output.mode ?? 'text'
+  const prefix = `${harnessId} adapter does not support ${mode} output mode.`
+
+  if (mode === 'structured') {
+    return [
+      prefix,
+      'The current model path does not support structured output for this harness.',
+      'Use text output and put the required JSON shape, field names, constraints, and validation rules directly in the prompt.'
+    ].join(' ')
+  }
+
+  if (mode === 'jsonl') {
+    return [
+      prefix,
+      'The current model path does not support native JSONL events for this harness.',
+      'Use text output and ask the model to emit one valid JSON object per line, or choose a harness with native JSONL support.'
+    ].join(' ')
+  }
+
+  return prefix
+}
+
+export function planTextCommand<Output extends RunOutputRequest>(input: {
+  harnessId: HarnessId
+  request: RunRequest<Output>
+  command: string
+  args: string[]
+  cwd: string
+  output: TextOutputRequest | JsonlOutputRequest
+}): CommandPlan<Output> {
+  return {
+    args: input.args,
+    command: input.command,
+    cwd: input.request.cwd ?? input.cwd,
+    env: input.request.env,
+    harnessId: input.harnessId,
+    output: input.output as Output,
+    stdin: input.request.stdin,
+    timeoutMs: input.request.timeoutMs
+  }
+}
+
+export function planCommand<Output extends RunOutputRequest>(input: {
+  harnessId: HarnessId
+  request: RunRequest<Output>
+  command: string
+  args: string[]
+  cwd: string
+  output: TextOutputRequest | JsonlOutputRequest | StructuredOutputRequest
+  env?: Record<string, string | undefined>
+}): CommandPlan<Output> {
+  return {
+    args: input.args,
+    command: input.command,
+    cwd: input.request.cwd ?? input.cwd,
+    env: mergeEnv(input.env, input.request.env),
+    harnessId: input.harnessId,
+    output: input.output as Output,
+    stdin: input.request.stdin,
+    timeoutMs: input.request.timeoutMs
+  }
+}
+
+function mergeEnv(
+  base: Record<string, string | undefined> | undefined,
+  patch: Record<string, string | undefined> | undefined
+): Record<string, string | undefined> | undefined {
+  const env = { ...base, ...patch }
+  return Object.keys(env).length > 0 ? env : undefined
+}
+
+export function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`
+}
+
+async function detectCommand(
+  config: BuiltInAdapterConfig,
+  context: HarnessContext | undefined
+): Promise<HarnessDetection> {
+  for (const command of config.commands) {
+    const resolved = await resolveCommand(command, context?.env)
+    if (!resolved) {
+      continue
+    }
+
+    const identity = await readIdentity(resolved, context, config.identityArgs ?? ['--version'])
+    if (identity && config.identity.test(identity)) {
+      return {
+        binary: { command: resolved, identity },
+        detected: true,
+        id: config.id
+      }
+    }
+  }
+
+  return { detected: false, id: config.id }
+}
+
+async function resolveCommand(
+  command: string,
+  env: Record<string, string | undefined> | undefined
+): Promise<string | undefined> {
+  if (command.includes('/')) {
+    return (await isExecutable(command)) ? command : undefined
+  }
+
+  for (const directory of (env?.PATH ?? process.env.PATH ?? '').split(delimiter)) {
+    if (!directory) {
+      continue
+    }
+
+    const candidate = join(directory, command)
+    if (await isExecutable(candidate)) {
+      return candidate
+    }
+  }
+
+  return undefined
+}
+
+async function isExecutable(path: string): Promise<boolean> {
+  try {
+    await access(path, 0b001)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function readIdentity(
+  command: string,
+  context: HarnessContext | undefined,
+  args: string[]
+): Promise<string | undefined> {
+  try {
+    const subprocess = Bun.spawn({
+      cmd: [command, ...args],
+      cwd: resolveCwd(context),
+      env: Object.fromEntries(
+        Object.entries({ ...process.env, ...(context?.env ?? {}) }).filter((entry): entry is [string, string] => {
+          return typeof entry[1] === 'string'
+        })
+      ),
+      stderr: 'pipe',
+      stdout: 'pipe'
+    })
+    const [exitCode, stdout, stderr] = await Promise.all([
+      subprocess.exited,
+      new Response(subprocess.stdout).text(),
+      new Response(subprocess.stderr).text()
+    ])
+    const identity = `${stdout}\n${stderr}`.trim()
+    return exitCode === 0 && identity.length > 0 ? identity : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function resolveCwd(context: HarnessContext | undefined): string {
+  return context?.cwd ?? process.cwd()
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/errors.ts

@@ -0,0 +1,43 @@
+import type { HarnessId, RunOutputRequest } from './types'
+
+export type OutputErrorKind = 'json_parse_failed' | 'structured_validation_failed'
+export type OutputErrorMode = Exclude<RunOutputRequest['mode'], 'text' | undefined>
+
+export class HarnessRunOutputError extends Error {
+  readonly kind: OutputErrorKind
+  readonly outputMode: OutputErrorMode
+  readonly finalText: string
+  readonly exitCode: number | null
+  readonly signal?: string
+  override readonly cause: unknown
+
+  constructor(input: {
+    kind: OutputErrorKind
+    outputMode: OutputErrorMode
+    finalText: string
+    exitCode: number | null
+    signal?: string
+    cause: unknown
+  }) {
+    super(`${input.outputMode} output failed: ${input.kind}`)
+    this.name = 'HarnessRunOutputError'
+    this.kind = input.kind
+    this.outputMode = input.outputMode
+    this.finalText = input.finalText
+    this.exitCode = input.exitCode
+    this.signal = input.signal
+    this.cause = input.cause
+  }
+}
+
+export class HarnessPlanError extends Error {
+  readonly harnessId: HarnessId
+  readonly kind: 'unsupported_output_mode' | 'unsupported_operation'
+
+  constructor(input: { harnessId: HarnessId; kind: HarnessPlanError['kind']; message: string }) {
+    super(input.message)
+    this.name = 'HarnessPlanError'
+    this.harnessId = input.harnessId
+    this.kind = input.kind
+  }
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+import './adapters'
+
+export { HarnessPlanError, HarnessRunOutputError } from './errors'
+export { harness } from './registry'
+export type {
+  CommandPlan,
+  ExtensionCheckResult,
+  ExtensionFacet,
+  ExtensionIssue,
+  ExtensionResourceKind,
+  ExtensionResources,
+  ExtensionResult,
+  HarnessAdapter,
+  HarnessContext,
+  HarnessDetection,
+  HarnessExtension,
+  HarnessHandle,
+  HarnessId,
+  HarnessRegistry,
+  HarnessRun,
+  HarnessRunEvent,
+  HarnessRunResult,
+  HealthFacet,
+  HealthReport,
+  HookResource,
+  JsonlOutputRequest,
+  McpServerResource,
+  ProcessFacet,
+  RunOutputRequest,
+  RunRequest,
+  StructuredOutputRequest,
+  StructuredRunResult,
+  TextOutputRequest
+} from './types'