@plimeor/harness 0.1.0

package/src/output.ts

@@ -0,0 +1,183 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
+import { HarnessRunOutputError } from './errors'
+import type { HarnessRunEvent, HarnessRunResult, RunOutputRequest, StructuredOutputRequest } from './types'
+
+export async function decodeRunOutput<Output extends RunOutputRequest>(input: {
+  output: Output
+  finalText: string
+  exitCode: number | null
+  signal?: string
+}): Promise<{ events: HarnessRunEvent[]; result: HarnessRunResult<Output> }> {
+  const mode = input.output.mode ?? 'text'
+
+  if (mode === 'text') {
+    return {
+      events: input.finalText ? [{ text: input.finalText, type: 'text' }] : [],
+      result: baseResult(input) as HarnessRunResult<Output>
+    }
+  }
+
+  if (mode === 'jsonl') {
+    const values = parseJsonLines(input.finalText, input.exitCode, input.signal)
+    return {
+      events: values.map(value => ({ type: 'json', value })),
+      result: {
+        ...baseResult(input),
+        finalText: extractFinalText(values) ?? input.finalText
+      } as HarnessRunResult<Output>
+    }
+  }
+
+  return (await decodeStructuredOutput(
+    input as { output: StructuredOutputRequest; finalText: string; exitCode: number | null; signal?: string }
+  )) as { events: HarnessRunEvent[]; result: HarnessRunResult<Output> }
+}
+
+function extractFinalText(values: unknown[]): string | undefined {
+  for (const value of values.toReversed()) {
+    const text = extractTextFromEvent(value)
+    if (text) {
+      return text
+    }
+  }
+
+  return undefined
+}
+
+function extractTextFromEvent(value: unknown): string | undefined {
+  if (!isRecord(value)) {
+    return undefined
+  }
+
+  const result = value.result
+  if (typeof result === 'string' && result.length > 0) {
+    return result
+  }
+
+  const structuredOutput = value.structured_output
+  if (structuredOutput !== undefined) {
+    return JSON.stringify(structuredOutput)
+  }
+
+  const item = value.item
+  if (isRecord(item) && item.type === 'agent_message' && typeof item.text === 'string' && item.text.length > 0) {
+    return item.text
+  }
+
+  const message = value.message
+  if (isRecord(message)) {
+    const messageText = extractTextFromContent(message.content)
+    if (messageText) {
+      return messageText
+    }
+  }
+
+  return undefined
+}
+
+function extractTextFromContent(content: unknown): string | undefined {
+  if (!Array.isArray(content)) {
+    return undefined
+  }
+
+  const text = content
+    .map(part => {
+      if (isRecord(part) && part.type === 'text' && typeof part.text === 'string') {
+        return part.text
+      }
+
+      return ''
+    })
+    .join('')
+
+  return text.length > 0 ? text : undefined
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function baseResult(input: { finalText: string; exitCode: number | null; signal?: string }): {
+  exitCode: number | null
+  signal?: string
+  finalText: string
+} {
+  return {
+    exitCode: input.exitCode,
+    finalText: input.finalText,
+    signal: input.signal
+  }
+}
+
+function parseJsonLines(text: string, exitCode: number | null, signal: string | undefined): unknown[] {
+  const lines = text.split(/\r?\n/).filter(line => line.trim().length > 0)
+
+  try {
+    return lines.map(line => JSON.parse(line))
+  } catch (cause) {
+    throw new HarnessRunOutputError({
+      cause,
+      exitCode,
+      finalText: text,
+      kind: 'json_parse_failed',
+      outputMode: 'jsonl',
+      signal
+    })
+  }
+}
+
+async function decodeStructuredOutput<Schema extends StandardSchemaV1>(input: {
+  output: StructuredOutputRequest<Schema>
+  finalText: string
+  exitCode: number | null
+  signal?: string
+}): Promise<{
+  events: HarnessRunEvent[]
+  result: HarnessRunResult<StructuredOutputRequest<Schema>>
+}> {
+  let value: unknown
+
+  try {
+    value = JSON.parse(input.finalText)
+  } catch (cause) {
+    throw new HarnessRunOutputError({
+      cause,
+      exitCode: input.exitCode,
+      finalText: input.finalText,
+      kind: 'json_parse_failed',
+      outputMode: 'structured',
+      signal: input.signal
+    })
+  }
+
+  const structuredValue = extractStructuredValue(value)
+  const validation = await input.output.schema['~standard'].validate(structuredValue)
+  if (validation.issues) {
+    throw new HarnessRunOutputError({
+      cause: validation.issues,
+      exitCode: input.exitCode,
+      finalText: input.finalText,
+      kind: 'structured_validation_failed',
+      outputMode: 'structured',
+      signal: input.signal
+    })
+  }
+
+  return {
+    events: [{ type: 'json', value }],
+    result: {
+      ...baseResult(input),
+      finalText: extractTextFromEvent(value) ?? input.finalText,
+      structured: validation.value as StandardSchemaV1.InferOutput<Schema>
+    }
+  }
+}
+
+function extractStructuredValue(value: unknown): unknown {
+  if (isRecord(value) && value.structured_output !== undefined) {
+    return value.structured_output
+  }
+
+  return value
+}

package/src/process.ts

@@ -0,0 +1,183 @@
+import { decodeRunOutput } from './output'
+import type { CommandPlan, HarnessId, HarnessRun, HarnessRunEvent, RunOutputRequest } from './types'
+
+class AsyncQueue<T> implements AsyncIterable<T> {
+  private readonly values: T[] = []
+  private readonly waiters: Array<(result: IteratorResult<T>) => void> = []
+  private closed = false
+
+  push(value: T): void {
+    const waiter = this.waiters.shift()
+    if (waiter) {
+      waiter({ done: false, value })
+      return
+    }
+
+    this.values.push(value)
+  }
+
+  close(): void {
+    this.closed = true
+    for (const waiter of this.waiters.splice(0)) {
+      waiter({ done: true, value: undefined })
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return {
+      next: () => this.next()
+    }
+  }
+
+  private next(): Promise<IteratorResult<T>> {
+    const value = this.values.shift()
+    if (value !== undefined) {
+      return Promise.resolve({ done: false, value })
+    }
+
+    if (this.closed) {
+      return Promise.resolve({ done: true, value: undefined })
+    }
+
+    return new Promise(resolve => {
+      this.waiters.push(resolve)
+    })
+  }
+}
+
+export function runCommandPlan<Output extends RunOutputRequest>(
+  harnessId: HarnessId,
+  plan: CommandPlan<Output>
+): HarnessRun<Output> {
+  if (plan.harnessId !== harnessId) {
+    throw new Error(`CommandPlan harnessId mismatch: expected ${harnessId}, received ${plan.harnessId}`)
+  }
+
+  const stdout = new AsyncQueue<Uint8Array>()
+  const stderr = new AsyncQueue<Uint8Array>()
+  const events = new AsyncQueue<HarnessRunEvent>()
+  const decoder = new TextDecoder()
+  let stdoutText = ''
+
+  const subprocess = Bun.spawn({
+    cmd: [plan.command, ...plan.args],
+    cwd: plan.cwd,
+    env: resolveEnv(plan.env),
+    stderr: 'pipe',
+    stdin: plan.stdin === undefined ? 'ignore' : 'pipe',
+    stdout: 'pipe'
+  })
+
+  if (plan.stdin !== undefined && subprocess.stdin) {
+    void writeStdin(subprocess.stdin, plan.stdin)
+  }
+
+  const timeout = plan.timeoutMs
+    ? setTimeout(() => {
+        subprocess.kill()
+      }, plan.timeoutMs)
+    : undefined
+
+  const stdoutDone = pipeStream(subprocess.stdout, stdout, chunk => {
+    const text = decoder.decode(chunk, { stream: true })
+    stdoutText += text
+  })
+  const stderrDone = pipeStream(subprocess.stderr, stderr)
+
+  const result = (async () => {
+    const exitCode = await subprocess.exited
+    clearTimeout(timeout)
+    await Promise.all([stdoutDone, stderrDone])
+    const tail = decoder.decode()
+    stdoutText += tail
+
+    try {
+      const decoded = await decodeRunOutput({
+        exitCode,
+        finalText: stdoutText,
+        output: plan.output,
+        signal: subprocess.signalCode ?? undefined
+      })
+
+      for (const event of decoded.events) {
+        events.push(event)
+      }
+      return decoded.result
+    } finally {
+      events.close()
+    }
+  })()
+
+  return {
+    events,
+    kill(signal?: string) {
+      subprocess.kill(signal as NodeJS.Signals | undefined)
+    },
+    plan,
+    result,
+    stderr,
+    stdout
+  }
+}
+
+export function createProcessRunner(harnessId: HarnessId): {
+  run<Output extends RunOutputRequest>(plan: CommandPlan<Output>): Promise<HarnessRun<Output>>
+} {
+  return {
+    async run<Output extends RunOutputRequest>(plan: CommandPlan<Output>): Promise<HarnessRun<Output>> {
+      return runCommandPlan(harnessId, plan)
+    }
+  }
+}
+
+function resolveEnv(patch: Record<string, string | undefined> | undefined): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const [name, value] of Object.entries(process.env)) {
+    if (typeof value === 'string') {
+      env[name] = value
+    }
+  }
+
+  for (const [name, value] of Object.entries(patch ?? {})) {
+    if (value === undefined) {
+      delete env[name]
+      continue
+    }
+
+    env[name] = value
+  }
+
+  return env
+}
+
+async function pipeStream(
+  stream: ReadableStream<Uint8Array> | null,
+  queue: AsyncQueue<Uint8Array>,
+  onChunk?: (chunk: Uint8Array) => void
+): Promise<void> {
+  if (!stream) {
+    queue.close()
+    return
+  }
+
+  const reader = stream.getReader()
+  try {
+    while (true) {
+      const chunk = await reader.read()
+      if (chunk.done) {
+        return
+      }
+
+      queue.push(chunk.value)
+      onChunk?.(chunk.value)
+    }
+  } finally {
+    queue.close()
+    reader.releaseLock()
+  }
+}
+
+async function writeStdin(stdin: Bun.FileSink, value: string | Uint8Array): Promise<void> {
+  stdin.write(value)
+  stdin.end()
+}

package/src/registry.ts

@@ -0,0 +1,34 @@
+import type { HarnessAdapter, HarnessContext, HarnessDetection, HarnessId, HarnessRegistry } from './types'
+
+function createHarnessRegistry(): HarnessRegistry {
+  const adapters: HarnessAdapter[] = []
+
+  return {
+    async detectAll(context?: HarnessContext): Promise<HarnessDetection[]> {
+      return Promise.all(adapters.map(adapter => adapter.detect(context)))
+    },
+
+    list(): HarnessAdapter[] {
+      return [...adapters]
+    },
+
+    async open(id: HarnessId, context?: HarnessContext) {
+      const adapter = adapters.find(candidate => candidate.id === id)
+      if (!adapter) {
+        throw new Error(`Unknown harness adapter: ${id}`)
+      }
+
+      return adapter.open(context)
+    },
+
+    use(adapter: HarnessAdapter): void {
+      if (adapters.some(candidate => candidate.id === adapter.id)) {
+        throw new Error(`Duplicate harness adapter: ${adapter.id}`)
+      }
+
+      adapters.push(adapter)
+    }
+  }
+}
+
+export const harness = createHarnessRegistry()

package/src/schema.ts

@@ -0,0 +1,18 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec'
+
+export function resolveOutputJsonSchema(schema: StandardSchemaV1): Record<string, unknown> | undefined {
+  if (!isStandardJsonSchema(schema)) {
+    return undefined
+  }
+
+  try {
+    return schema['~standard'].jsonSchema.output({ target: 'draft-07' })
+  } catch {
+    return undefined
+  }
+}
+
+function isStandardJsonSchema(schema: StandardSchemaV1): schema is StandardSchemaV1 & StandardJSONSchemaV1 {
+  const candidate = schema as StandardSchemaV1 & Partial<StandardJSONSchemaV1>
+  return typeof candidate['~standard'].jsonSchema?.output === 'function'
+}

package/src/types.ts

@@ -0,0 +1,166 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
+export type HarnessId = 'claude' | 'codex' | 'kiro' | 'pi' | (string & {})
+
+export type HarnessContext = {
+  /** Default working directory for adapter operations; relative extension paths resolve from here. */
+  cwd?: string
+  /** Base environment available to detection, planning, and adapter-owned native commands. */
+  env?: Record<string, string | undefined>
+  /** User home directory used for user-scope native config resolution. */
+  home?: string
+}
+
+export type HarnessRegistry = {
+  use(adapter: HarnessAdapter): void
+  list(): HarnessAdapter[]
+  detectAll(context?: HarnessContext): Promise<HarnessDetection[]>
+  open(id: HarnessId, context?: HarnessContext): Promise<HarnessHandle>
+}
+
+export type HarnessAdapter = {
+  id: HarnessId
+  detect(context?: HarnessContext): Promise<HarnessDetection>
+  open(context?: HarnessContext): Promise<HarnessHandle>
+}
+
+export type HarnessHandle = {
+  detection: HarnessDetection
+  health: HealthFacet
+  process: ProcessFacet
+  extensions: ExtensionFacet
+}
+
+export type HarnessDetection = {
+  id: HarnessId
+  detected: boolean
+  binary?: {
+    /** Executable name or path used to invoke the detected harness CLI. */
+    command: string
+    /** Adapter-verified identity string, such as a version or product marker. */
+    identity?: string
+  }
+}
+
+export type HealthFacet = {
+  check(): Promise<HealthReport>
+}
+
+export type HealthReport = { success: true } | { success: false; message: string }
+
+export type ProcessFacet = {
+  plan<Output extends RunOutputRequest = TextOutputRequest>(request: RunRequest<Output>): Promise<CommandPlan<Output>>
+  run<Output extends RunOutputRequest = TextOutputRequest>(request: RunRequest<Output>): Promise<HarnessRun<Output>>
+  run<Output extends RunOutputRequest = TextOutputRequest>(plan: CommandPlan<Output>): Promise<HarnessRun<Output>>
+}
+
+export type RunRequest<Output extends RunOutputRequest = TextOutputRequest> = {
+  prompt: string
+  /** Requested working directory before adapter resolution. */
+  cwd?: string
+  stdin?: string | Uint8Array
+  /** Process environment patch requested by the caller for this run. */
+  env?: Record<string, string | undefined>
+  /** Defaults to text output when omitted. */
+  output?: Output
+  timeoutMs?: number
+}
+
+export type RunOutputRequest = TextOutputRequest | JsonlOutputRequest | StructuredOutputRequest
+
+export type TextOutputRequest = { mode?: 'text' }
+
+export type JsonlOutputRequest = { mode: 'jsonl' }
+
+export type StructuredOutputRequest<Schema extends StandardSchemaV1 = StandardSchemaV1> = {
+  mode: 'structured'
+  schema: Schema
+}
+
+export type CommandPlan<Output extends RunOutputRequest = TextOutputRequest> = {
+  harnessId: HarnessId
+  /** Executable name or path to spawn; arguments stay in args. */
+  command: string
+  args: string[]
+  /** Resolved working directory used by process.run. */
+  cwd: string
+  /** Process environment patch: string sets a variable, undefined removes it. */
+  env?: Record<string, string | undefined>
+  stdin?: string | Uint8Array
+  output: Output
+  timeoutMs?: number
+}
+
+export type HarnessRun<Output extends RunOutputRequest = TextOutputRequest> = {
+  plan: CommandPlan<Output>
+  stdout: AsyncIterable<Uint8Array>
+  stderr: AsyncIterable<Uint8Array>
+  events: AsyncIterable<HarnessRunEvent>
+  result: Promise<HarnessRunResult<Output>>
+  kill(signal?: string): void
+}
+
+export type HarnessRunEvent = { type: 'text'; text: string } | { type: 'json'; value: unknown }
+
+export type HarnessRunResult<Output extends RunOutputRequest = TextOutputRequest> = {
+  exitCode: number | null
+  signal?: string
+  finalText: string
+} & StructuredRunResult<Output>
+
+export type StructuredRunResult<Output extends RunOutputRequest> =
+  Output extends StructuredOutputRequest<infer Schema>
+    ? { structured: StandardSchemaV1.InferOutput<Schema> }
+    : { structured?: never }
+
+export type ExtensionFacet = {
+  check(extension: HarnessExtension): Promise<ExtensionCheckResult>
+  install(extension: HarnessExtension): Promise<ExtensionResult>
+  uninstall(extensionId: string): Promise<ExtensionResult>
+}
+
+export type HarnessExtension = {
+  /** Stable extension id used by adapter-owned install records and uninstall. */
+  id: string
+  resources: ExtensionResources
+}
+
+export type ExtensionResources = {
+  /** Filesystem paths to skill files or directories; relative paths resolve from HarnessContext.cwd. */
+  skills?: string[]
+  hooks?: HookResource[]
+  mcpServers?: Record<string, McpServerResource>
+}
+
+export type ExtensionResourceKind = keyof ExtensionResources
+
+export type McpServerResource = {
+  /** Executable name or path for the stdio MCP server; arguments stay in args. */
+  command: string
+  args?: string[]
+  /** Environment variables added for this MCP server process. */
+  env?: Record<string, string>
+}
+
+export type HookResource = {
+  /** Stable hook resource name within this extension. */
+  name: string
+  /** Native hook event name validated by the adapter. */
+  event: string
+  /** Command string installed into the target harness native hook config. */
+  command: string
+}
+
+export type ExtensionResult = {
+  success: boolean
+  issues: ExtensionIssue[]
+}
+
+export type ExtensionCheckResult = {
+  compatible: boolean
+  issues: ExtensionIssue[]
+}
+
+export type ExtensionIssue =
+  | { kind: 'unsupported'; resourceKind: ExtensionResourceKind; resourceName?: string; reason: string }
+  | { kind: 'conflict'; resourceKind?: ExtensionResourceKind; resourceName?: string; reason: string }