@plimeor/harness 0.1.0

package/README.md

@@ -0,0 +1,221 @@
+# @plimeor/harness
+
+Drive CLI coding agents from one TypeScript API.
+
+`@plimeor/harness` lets your app detect installed agents, check whether they
+can answer a prompt, run tasks, decode common output modes, and install
+user-scope integrations such as skills, MCP servers, and hooks.
+
+It is an SDK only. It does not expose a CLI.
+
+## Install
+
+```sh
+bun add @plimeor/harness
+```
+
+## Pick an Agent
+
+Importing the package registers the built-in adapters.
+
+```ts
+import { harness } from '@plimeor/harness'
+
+const available = await harness.detectAll()
+
+for (const agent of available) {
+  if (agent.detected) {
+    console.log(agent.id, agent.binary?.identity)
+  }
+}
+```
+
+Open the adapter you want to use:
+
+```ts
+const handle = await harness.open('codex', {
+  cwd: process.cwd()
+})
+```
+
+## Check Health
+
+Health checks answer one product question: can this CLI run right now?
+
+```ts
+const health = await handle.health.check()
+
+if (!health.success) {
+  throw new Error(health.message)
+}
+```
+
+A successful report means the CLI is installed and produced output for a smoke
+prompt. Codex and Claude health checks also verify that `google.com` is
+reachable before running the smoke prompt. A failed report includes a message
+suitable for showing to a user.
+
+## Run a Task
+
+For the common path, pass a request directly to `process.run()`.
+
+```ts
+const run = await handle.process.run({
+  prompt: 'Summarize this repository in three bullets.',
+  timeoutMs: 60_000
+})
+
+const result = await run.result
+
+console.log(result.finalText)
+```
+
+`run.stdout` and `run.stderr` are async iterables, so you can stream raw process
+output while still awaiting `run.result`.
+
+Use `plan()` first when your app needs to show or approve the exact command
+before spawning it:
+
+```ts
+const plan = await handle.process.plan({
+  prompt: 'Summarize this repository in three bullets.'
+})
+
+console.log(plan.command, plan.args)
+
+const run = await handle.process.run(plan)
+```
+
+## Output Modes
+
+Text output is the default:
+
+```ts
+const run = await handle.process.run({
+  prompt: 'Reply with OK.'
+})
+```
+
+Use JSONL when the adapter supports native JSON events:
+
+```ts
+const run = await handle.process.run({
+  output: { mode: 'jsonl' },
+  prompt: 'Reply with OK.'
+})
+
+for await (const event of run.events) {
+  if (event.type === 'json') {
+    console.log(event.value)
+  }
+}
+```
+
+Use structured output when you need a validated object. Schemas use
+`StandardSchemaV1`, so libraries such as Valibot can provide the schema.
+
+```ts
+import * as v from 'valibot'
+
+const Answer = v.object({
+  answer: v.string()
+})
+
+const run = await handle.process.run({
+  output: { mode: 'structured', schema: Answer },
+  prompt: 'Return JSON with an answer field.'
+})
+
+const result = await run.result
+
+console.log(result.structured.answer)
+```
+
+Unsupported output modes fail during `process.plan()` with `HarnessPlanError`.
+Invalid JSON or failed structured validation fails from `run.result` with
+`HarnessRunOutputError`.
+
+## Install Extensions
+
+Extensions describe user-scope resources your app wants the selected agent to
+know about.
+
+```ts
+const extension = {
+  id: 'acme-tools',
+  resources: {
+    skills: ['./skills/review'],
+    mcpServers: {
+      'acme-tools__docs': {
+        command: 'bun',
+        args: ['run', 'docs-mcp.ts'],
+        env: { DOCS_ROOT: '/workspace/docs' }
+      }
+    },
+    hooks: [
+      {
+        name: 'acme-tools__pre-tool',
+        event: 'PreToolUse',
+        command: 'bun run hooks/pre-tool.ts'
+      }
+    ]
+  }
+}
+```
+
+Check compatibility before installing:
+
+```ts
+const check = await handle.extensions.check(extension)
+
+if (!check.compatible) {
+  console.error(check.issues)
+  return
+}
+```
+
+Install and uninstall through the adapter:
+
+```ts
+const installed = await handle.extensions.install(extension)
+
+if (!installed.success) {
+  console.error(installed.issues)
+}
+
+await handle.extensions.uninstall('acme-tools')
+```
+
+Skills are filesystem paths. Relative paths resolve from `HarnessContext.cwd`.
+MCP servers are stdio process configs. Hooks use the target agent's native event
+names.
+
+Install is all-or-nothing: unsupported resources or conflicts prevent native
+writes. Uninstall only removes resources that the adapter can still prove belong
+to the extension.
+
+## Built-In Adapters
+
+| Adapter | CLI command | Output modes | Extensions |
+| --- | --- | --- | --- |
+| `codex` | `codex` | `text`, `jsonl`, `structured` | skills, MCP servers, hooks |
+| `claude` | `claude` | `text`, `jsonl`, `structured` | skills, MCP servers, hooks |
+| `kiro` | `kiro-cli` | `text` | skills, MCP servers, hooks |
+| `pi` | `pi` | `text`, `jsonl` | skills |
+
+## Context
+
+Pass `HarnessContext` when your app needs deterministic paths or environment:
+
+```ts
+const handle = await harness.open('kiro', {
+  cwd: '/workspace/project',
+  env: { KIRO_HOME: '/tmp/kiro-home' },
+  home: '/tmp/user-home'
+})
+```
+
+- `cwd` is the default working directory for runs and relative extension paths.
+- `env` patches the process environment used by detection, planning, and native
+  adapter commands.
+- `home` controls where user-scope config is resolved.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "description": "Unified infrastructure contract for CLI coding-agent harnesses",
+  "homepage": "https://github.com/plimeor/labs/tree/main/packages/harness",
+  "name": "@plimeor/harness",
+  "type": "module",
+  "types": "./src/index.ts",
+  "version": "0.1.0",
+  "bugs": {
+    "url": "https://github.com/plimeor/labs/issues"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./adapters": "./src/adapters/index.ts",
+    "./adapters/claude": "./src/adapters/claude.ts",
+    "./adapters/codex": "./src/adapters/codex.ts",
+    "./adapters/kiro": "./src/adapters/kiro.ts",
+    "./adapters/pi": "./src/adapters/pi.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/harness",
+    "type": "git",
+    "url": "git+https://github.com/plimeor/labs.git"
+  },
+  "scripts": {
+    "check": "tsc --noEmit -p tsconfig.json",
+    "lint": "biome check src test",
+    "prepack": "bun src/index.ts",
+    "test": "bun test test"
+  }
+}

package/src/adapters/claude.ts

@@ -0,0 +1,112 @@
+import { harness } from '../registry'
+import { resolveOutputJsonSchema } from '../schema'
+import type {
+  HarnessContext,
+  JsonlOutputRequest,
+  RunOutputRequest,
+  RunRequest,
+  StructuredOutputRequest,
+  TextOutputRequest
+} from '../types'
+import { configDirectory, createExtensionFacet } from './extensions'
+import { createBuiltInAdapter, planCommand, planTextCommand, unsupportedOutputMode } from './shared'
+
+const HARNESS_ID = 'claude'
+
+export const claudeAdapter = createBuiltInAdapter({
+  commands: ['claude'],
+  id: HARNESS_ID,
+  identity: /claude/i,
+  installHint: 'Install Claude Code and ensure `claude --version` is available on PATH.',
+  requiresGoogleAccessBeforeSmoke: true,
+  extensions(context: HarnessContext | undefined) {
+    const directory = configDirectory(context?.home, '.claude')
+    return createExtensionFacet({
+      configDirectory: directory,
+      context,
+      harnessId: HARNESS_ID,
+      mcp: { configFile: `${directory}/mcp.json`, kind: 'claude-json' },
+      skillsDirectory: `${directory}/skills`,
+      hooks: {
+        kind: 'json-hooks',
+        settingsFile: `${directory}/settings.json`,
+        events: [
+          'SessionStart',
+          'Setup',
+          'UserPromptSubmit',
+          'UserPromptExpansion',
+          'PreToolUse',
+          'PermissionRequest',
+          'PermissionDenied',
+          'PostToolUse',
+          'PostToolUseFailure',
+          'PostToolBatch',
+          'Notification',
+          'MessageDisplay',
+          'SubagentStart',
+          'SubagentStop',
+          'TaskCreated',
+          'TaskCompleted',
+          'Stop',
+          'StopFailure',
+          'TeammateIdle',
+          'InstructionsLoaded',
+          'ConfigChange',
+          'CwdChanged',
+          'FileChanged',
+          'WorktreeCreate',
+          'WorktreeRemove',
+          'PreCompact',
+          'PostCompact',
+          'Elicitation',
+          'ElicitationResult',
+          'SessionEnd'
+        ]
+      }
+    })
+  },
+  plan(request: RunRequest<RunOutputRequest>, command: string, cwd: string) {
+    const output = request.output ?? ({ mode: 'text' } satisfies TextOutputRequest)
+    if (output.mode === 'jsonl') {
+      return planTextCommand({
+        args: ['-p', '--output-format', 'json', request.prompt],
+        command,
+        cwd,
+        harnessId: HARNESS_ID,
+        output: output satisfies JsonlOutputRequest,
+        request
+      })
+    }
+
+    if (output.mode === 'structured') {
+      const jsonSchema = resolveOutputJsonSchema(output.schema)
+      if (!jsonSchema) {
+        return unsupportedOutputMode(HARNESS_ID, output)
+      }
+
+      return planCommand({
+        args: ['-p', '--output-format', 'json', '--json-schema', JSON.stringify(jsonSchema), request.prompt],
+        command,
+        cwd,
+        harnessId: HARNESS_ID,
+        output: output satisfies StructuredOutputRequest,
+        request
+      })
+    }
+
+    if (!output.mode || output.mode === 'text') {
+      return planTextCommand({
+        args: ['-p', '--output-format', 'text', request.prompt],
+        command,
+        cwd,
+        harnessId: HARNESS_ID,
+        output: { mode: 'text' },
+        request
+      })
+    }
+
+    return unsupportedOutputMode(HARNESS_ID, output)
+  }
+})
+
+harness.use(claudeAdapter)

package/src/adapters/codex.ts

@@ -0,0 +1,118 @@
+import { harness } from '../registry'
+import { resolveOutputJsonSchema } from '../schema'
+import type {
+  HarnessContext,
+  JsonlOutputRequest,
+  RunOutputRequest,
+  RunRequest,
+  StructuredOutputRequest,
+  TextOutputRequest
+} from '../types'
+import { configDirectory, createExtensionFacet } from './extensions'
+import { createBuiltInAdapter, planCommand, planTextCommand, shellQuote, unsupportedOutputMode } from './shared'
+
+const HARNESS_ID = 'codex'
+
+export const codexAdapter = createBuiltInAdapter({
+  commands: ['codex'],
+  id: HARNESS_ID,
+  identity: /codex/i,
+  installHint: 'Install OpenAI Codex CLI and ensure `codex --version` is available on PATH.',
+  requiresGoogleAccessBeforeSmoke: true,
+  extensions(context: HarnessContext | undefined) {
+    const directory = configDirectory(context?.home, '.codex')
+    return createExtensionFacet({
+      configDirectory: directory,
+      context,
+      harnessId: HARNESS_ID,
+      mcp: { configFile: `${directory}/config.toml`, kind: 'codex-toml' },
+      skillsDirectory: `${directory}/skills`,
+      hooks: {
+        kind: 'json-hooks',
+        settingsFile: `${directory}/hooks.json`,
+        events: [
+          'PermissionRequest',
+          'PostCompact',
+          'PostToolUse',
+          'PreCompact',
+          'PreToolUse',
+          'SessionStart',
+          'Stop',
+          'SubagentStart',
+          'SubagentStop',
+          'UserPromptSubmit'
+        ]
+      }
+    })
+  },
+  plan(request: RunRequest<RunOutputRequest>, command: string, cwd: string) {
+    const output = request.output ?? ({ mode: 'text' } satisfies TextOutputRequest)
+    if (output.mode === 'jsonl') {
+      return planTextCommand({
+        args: ['exec', '--skip-git-repo-check', '--json', request.prompt],
+        command,
+        cwd,
+        harnessId: HARNESS_ID,
+        output: output satisfies JsonlOutputRequest,
+        request
+      })
+    }
+
+    if (output.mode === 'structured') {
+      const jsonSchema = resolveOutputJsonSchema(output.schema)
+      if (!jsonSchema) {
+        return unsupportedOutputMode(HARNESS_ID, output)
+      }
+
+      return planCommand({
+        args: ['-lc', codexStructuredCommand(command, request.prompt, JSON.stringify(jsonSchema))],
+        command: 'sh',
+        cwd,
+        harnessId: HARNESS_ID,
+        output: output satisfies StructuredOutputRequest,
+        request
+      })
+    }
+
+    if (!output.mode || output.mode === 'text') {
+      return planTextCommand({
+        args: ['exec', '--skip-git-repo-check', '--color', 'never', request.prompt],
+        command,
+        cwd,
+        harnessId: HARNESS_ID,
+        output: { mode: 'text' },
+        request
+      })
+    }
+
+    return unsupportedOutputMode(HARNESS_ID, output)
+  }
+})
+
+harness.use(codexAdapter)
+
+function codexStructuredCommand(command: string, prompt: string, jsonSchema: string): string {
+  return [
+    'schema=$(mktemp /tmp/codex-schema.XXXXXX)',
+    'out=$(mktemp /tmp/codex-output.XXXXXX)',
+    'cleanup() { rm -f "$schema" "$out"; }',
+    'trap cleanup EXIT',
+    `printf %s ${shellQuote(jsonSchema)} > "$schema"`,
+    [
+      shellQuote(command),
+      'exec',
+      '--skip-git-repo-check',
+      '--color',
+      'never',
+      '--output-schema',
+      '"$schema"',
+      '--output-last-message',
+      '"$out"',
+      shellQuote(prompt),
+      '>/dev/null'
+    ].join(' '),
+    'code=$?',
+    '[ -f "$out" ] && cat "$out"',
+    'exit "$code"'
+  ].join('; ')
+}