nerve/.knowledge/adapter.md

Agent Adapters (RFC-003)

Adapter = capability. Role = scenario. Workflows declare adapters directly via import.

AgentFn Protocol

type AgentFn = (ctx: ThreadContext, systemPrompt: string) => Promise<string>

• Input: thread context ({ threadId, start, steps }) + system prompt (role identity)
• Output: single-shot Promise<string> — no streaming support
• Adapter handles tool-specific details internally

Streaming Limitations

The AgentFn protocol does not support streaming responses (AsyncIterable<string> or ReadableStream). It's strictly limited to single-shot Promise<string> returns.

For long-running or incremental agent outputs:

• CLI tools buffer full output until completion
• Timeout enforcement via timeoutMs (default 300s)
• No intermediate results exposed to workflow logic
• Progress indication happens at the CLI tool level only

Available Adapters

Package	Adapter	Tool
@uncaged/nerve-adapter-cursor	cursorAdapter / createCursorAdapter()	cursor-agent CLI
@uncaged/nerve-adapter-hermes	hermesAdapter / createHermesAdapter()	hermes chat CLI

Each exports a default instance (sensible defaults) and a factory for custom config.

Usage in Workflows

Adapters are passed directly to createRole:

import { createRole } from "@uncaged/nerve-workflow-utils";
import { cursorAdapter } from "@uncaged/nerve-adapter-cursor";

const coder = createRole(cursorAdapter, prompt, schema, extractConfig);

No registry, no config indirection. TypeScript catches missing adapters at compile time.

Extract Layer

Parses agent raw string → typed meta. Configured in nerve.yaml:

extract:
  provider: dashscope
  model: qwen-plus

Two-level merge: global → role override. Retry once on parse failure (feeds error back to LLM), then throw ExtractError.

Error Handling

When adapters' underlying CLI tools (e.g., cursor-agent or hermes) fail, errors are surfaced synchronously via rejection with no fallback/retry logic:

• Missing/unavailable tool: spawn_failed error when CLI binary not found in $PATH
• Non-zero exit code: non_zero_exit error with captured stdout/stderr
• Timeout: timeout error when execution exceeds configured timeoutMs
• Abort signal: aborted error when AbortSignal triggers cancellation

All errors are immediately thrown as Error instances with descriptive messages (e.g., "cursor-agent: exitCode=7 stdout=... stderr=..."). No automatic retries or fallback adapters.