@navels/neal 0.1.0

package/docs/providers.md

@@ -0,0 +1,751 @@
+# Provider Adapters
+
+Neal's writer-run provider layer is an internal extension point for built-in
+agent SDK adapters. A provider adapter maps one SDK's sessions, tools,
+structured-output behavior, errors, usage data, and stream/message events into
+Neal-owned contracts.
+
+Neal currently ships built-in adapters for:
+
+- `openai-codex`
+- `anthropic-claude`
+- `openai-compatible` (structured-advisor/reviewer roles only, backed by the
+  AI SDK's OpenAI-compatible chat provider; see
+  [OpenAI-Compatible Endpoints](#openai-compatible-endpoints))
+- `generic-agentic` (Neal-owned agentic writer for any OpenAI-compatible
+  tool-calling endpoint; coder-first, with a tool-capable read-only
+  structured-advisor/reviewer path; see
+  [Generic Agentic Writer](#generic-agentic-writer))
+
+Neal does not currently load external provider plugins or discover
+npm-installed providers. Public `neal review` is a separate read-only findings
+flow that uses configured provider adapters; it is not a writer-run mode and is
+not a registered provider id.
+
+`neal setup` can inspect local built-in provider runtime availability while
+writing explicit writer-run defaults. That detection is intentionally local and
+non-connectivity-based: it checks runtime surfaces such as the OpenAI Codex SDK
+entrypoint and Claude SDK-bundled or standalone executable paths, but it does
+not authenticate, send prompts, collect secrets, or verify account state. Use
+`neal check` after setup for the live provider connectivity prompt.
+
+## Contract Overview
+
+Provider contracts live in `src/neal/providers/types.ts`. A built-in provider
+module should export a `NealProviderDefinition` plus any focused test hooks it
+needs.
+
+The provider definition includes:
+
+- `id`: the provider id used in config and run state.
+- `displayName`: a human-readable provider name.
+- `capabilities`: role-by-role capability declarations.
+- `createCoderAdapter`: optional factory for coder turns.
+- `createStructuredAdvisorAdapter`: optional factory for structured-advisor
+  turns.
+
+Registered provider definitions are owned by `src/neal/providers/registry.ts`.
+Config parsing, run-state hydration, adapter lookup, and writer-run capability
+checks all resolve provider identity through that registry.
+
+## Roles
+
+Neal exposes three effective agent roles for writer runs:
+
+- `planner`: writes and revises plan artifacts through the coder adapter surface.
+  It inherits the coder provider/model unless configured explicitly.
+- `coder`: runs ordinary implementation turns and may receive an optional
+  structured response schema.
+- `reviewer`: runs schema-oriented rounds for review, plan review, support, and
+  final completion review work through the structured-advisor adapter surface.
+
+Provider capability roles remain `coder` and `structured-advisor`; `planner` is
+a Neal role label backed by the configured provider's coder adapter. The same
+provider may support both capability roles, or only one. The checked-in config
+template and first-run setup examples use `openai-codex` for the coder role and
+`anthropic-claude` for the reviewer role, but fresh writer runs still require
+explicit coder and reviewer provider config from `neal setup` or config files.
+Final completion summary currently uses the configured coder provider through
+the structured-advisor adapter, so a writer-ready coder provider must support
+both coder and structured-advisor paths.
+
+## Capabilities
+
+Each provider capability role declares:
+
+- whether the role is supported
+- read, write, and shell tool access
+- session resume support
+- model override support
+- Neal structured control protocol support
+- usage reporting support
+
+Capabilities are enforced before writer work starts or resumes. Neal requires
+the planner and coder effective roles to resolve to providers with the coder
+capability, write and shell access, and Neal structured control protocol support.
+The reviewer effective role must resolve to a provider with the
+structured-advisor capability and either read tool access or structured-output
+support that lets Neal inline the review context (full diff, plan document, and
+run artifacts) directly into reviewer prompts. Session resume support is
+required when a persisted session handle is present.
+
+Current built-in capabilities are intentionally conservative:
+
+- OpenAI Codex supports coder and structured-advisor roles. The coder role is
+  read, write, and shell capable because the current SDK configuration uses
+  broad local access. The structured-advisor (reviewer) role is read capable
+  but never write or shell capable (see
+  [The Read-Only Reviewer Invariant](#the-read-only-reviewer-invariant)).
+- Anthropic Claude supports coder and structured-advisor roles. The coder role
+  is read, write, and shell capable. The structured-advisor (reviewer) role is
+  read capable but never write or shell capable.
+- OpenAI-Compatible supports only the structured-advisor role, with no read,
+  write, or shell tool access and no session resume. Neal compensates by
+  inlining reviewer context into prompts; see
+  [OpenAI-Compatible Endpoints](#openai-compatible-endpoints).
+- Generic Agentic supports coder and structured-advisor roles. The coder role
+  is read, write, and shell capable through Neal-owned tools executed locally.
+  The structured-advisor role is read capable (a read-only toolset; no write
+  or shell access), so a generic reviewer inspects the repository directly
+  with read tools instead of receiving Neal-inlined context. Neither role
+  supports session resume. See
+  [Generic Agentic Writer](#generic-agentic-writer).
+
+The `coder` capability describes adapter paths, not a global promise that every
+writer-run workflow is read-only: writer-run coder turns use provider SDKs with
+broad local permissions. The separate public `neal review` command enforces its
+own read-only boundary in the review command flow.
+
+### Coder Tool Policy Enforcement
+
+Plan-authoring rounds pass a `toolPolicy` (`allowedWritePaths` restricted to
+the plan document, `allowRun: false`) to the coder adapter. Enforcement
+strength is adapter-specific and mechanical where each SDK allows it:
+
+- `generic-agentic`: full jail. The policy selects the Neal-owned plan-author
+  toolset — writes only to the allowlisted paths, no shell tool at all.
+- `anthropic-claude`: tool exclusion plus a path callback. `allowRun: false`
+  removes Bash from the turn's tools list, and a PreToolUse hook denies any
+  write-class tool call whose resolved path is not allowlisted.
+- `openai-codex`: sandbox downgrade only. The jailed turn's thread runs under
+  the `workspace-write` sandbox instead of `danger-full-access`. The Codex SDK
+  has no per-tool-call hook, so path-level confinement is not enforceable:
+  shell still runs inside the sandbox and can write any workspace path, not
+  just the plan document.
+
+Rounds without a `toolPolicy` are unaffected on every adapter: ordinary coder
+scope rounds keep full access because verification legitimately runs commands.
+
+### The Read-Only Reviewer Invariant
+
+A reviewer exists to *judge*, never to *modify* or *re-execute*. Neal enforces
+this structurally: every *supported* `structured-advisor` capability has
+`write: false` and `shell: false`. The invariant constrains only `write` and
+`shell` — `read` is intentionally left unconstrained, so it stays `true` for
+read-tool reviewers (`openai-codex`, `anthropic-claude`, `generic-agentic`) and
+`false` for the inline-context reviewer (`openai-compatible`, which reviews from
+Neal-inlined context rather than read tools).
+
+`src/neal/providers/registry.ts` asserts this over every registered provider
+definition — built-in or test-registered — at the definition-resolution
+chokepoint and at test registration time, so no provider definition can ever
+declare a writing or shell-running reviewer. The assertion checks only the
+`write`/`shell` half; it never constrains `read`, and it never touches the
+`coder` capability (coders keep `write`/`shell`).
+
+Two consequences follow from no reviewer holding shell access:
+
+- Reviewers never re-run tests or other verification. Verification happens once,
+  performed by the coder; the reviewer trusts the coder's reported result plus
+  its own reading of the diff and (for read-tool reviewers) the repository.
+- Reviewers never mutate the checkout. A review produces a verdict and findings,
+  not edits.
+
+Usage reporting is `opportunistic`: providers emit usage only when the SDK
+event or result supplies it.
+
+### Review Doctrine Access Modes
+
+Reviewer prompts render Neal's shared review doctrine in one of three access
+modes, derived from the configured reviewer provider's structured-advisor
+tool access:
+
+- `read-only` (read access without shell access; `openai-codex`,
+  `anthropic-claude`, and `generic-agentic` today): the reviewer is instructed
+  to inspect the repository through read tools only — reading changed files and
+  searching the tree — and is never instructed to run commands, run tests, or
+  use scratch directories. Commit-range visibility depends on whether the
+  provider exposes its own range-diff tool:
+  - `generic-agentic` declares a read-only `git_diff` commit-range tool
+    (`providesRangeDiffTool`), so its reviewer inspects the range with that tool
+    and receives no inlined diff.
+  - native read-only reviewers such as `openai-codex` and `anthropic-claude`
+    have read and search tools but no commit-range diff tool, so Neal inlines
+    the commit-range diff into the reviewer prompt as the source of truth for
+    what the range changed (including deletions and renames that head-state file
+    reads cannot reveal), and the reviewer uses its read/search tools to verify
+    the surrounding code.
+
+  In both branches the doctrine states that absence from a diff is not evidence
+  of absence from the repository: the reviewer must open files with read tools
+  before claiming a missing import or declaration.
+- `no-read` (no repository read access; `openai-compatible` today): Neal
+  inlines the review context — the full diff, plan document content, review
+  history, and run artifacts, with per-section truncation caps — directly
+  into reviewer prompts, and the doctrine never instructs repository, file,
+  tool, or shell access.
+- `tool-access` (read and shell access): a reviewer is instructed to inspect
+  and execute against the repository directly. Because the read-only reviewer
+  invariant forbids any supported `structured-advisor` capability from holding
+  shell access (see
+  [The Read-Only Reviewer Invariant](#the-read-only-reviewer-invariant)), no
+  built-in reviewer resolves to this mode today; it would require a
+  shell-capable reviewer, which the registry assertion rejects.
+
+Neither shell-less read-tool reviewers nor the inline-context reviewer are ever
+instructed to run verification: the doctrine reflects that verification is the
+coder's, trusted by the reviewer's reading or inlined context. Write access does
+not affect review doctrine: reviews never instruct repository mutation, and no
+supported reviewer capability declares write access in any case.
+
+## Runtime Turns
+
+Provider adapters receive Neal-owned turn arguments rather than reading Neal
+configuration directly.
+
+Plain coder turns receive:
+
+- `cwd`
+- `prompt`
+- `inactivityTimeoutMs`
+- optional `resumeHandle`
+- optional structured `outputSchema`, retained only for raw coder prompt
+  compatibility outside Neal product control paths
+- optional `onSessionStarted` callback
+- optional provider event sink
+
+Structured coder turns receive:
+
+- `label`
+- `cwd`
+- `prompt`
+- `schema`
+- `inactivityTimeoutMs`
+- optional `resumeHandle`
+- optional `onSessionStarted` callback
+- optional provider event sink
+
+Structured-advisor turns receive:
+
+- `label`
+- `cwd`
+- `prompt`
+- `schema`
+- `inactivityTimeoutMs`
+- `apiRetryLimit`
+- optional `model`
+- optional `resumeHandle`
+- optional provider event sink
+
+The orchestration and round layers own timeout/retry configuration lookup,
+schema validation, state transitions, review decisions, source-control policy,
+and terminal narration policy. Provider adapters own SDK initialization,
+message or stream collection, SDK session mapping, SDK error normalization, and
+SDK telemetry mapping.
+
+All turn argument shapes also accept an optional `signal` (`AbortSignal`).
+Adapters must treat an aborted signal as a request to terminate the in-flight
+SDK turn and surface a normalized provider error rather than hanging.
+
+### Turn Liveness
+
+Neal layers two independent timeouts over every provider turn:
+
+- `neal.agent_turn_startup_timeout_ms` (default `300000`) bounds startup
+  silence: the window after a turn starts during which the provider has shown
+  no observable progress (no tool use, commands, file changes, assistant text,
+  structured output, or usage). `session_started` and `turn_started` keep the
+  transport alive but do not count as progress.
+- `neal.inactivity_timeout_ms` (default `600000`) bounds active-work idle time
+  and is owned by the provider adapters. Once a turn shows any observable
+  progress, the startup timer disarms permanently and only this timeout
+  applies.
+
+When the startup timer fires, Neal aborts the silent attempt via the turn's
+`signal` and retries the same turn up to `neal.agent_turn_retry_limit` times
+(default `1`). This means Neal may rerun a turn even though the provider never
+reported an error: the provider went silent before doing any work, which is
+indistinguishable from a stalled SDK stream. Retries are safe because zero
+observable progress was made. Keep `agent_turn_retry_limit` low (the default of
+1 is recommended); persistent startup silence usually indicates a provider or
+network problem that more retries will not fix. Coder turns that resume an
+existing session are never retried by this layer; the orchestrator's existing
+fresh-session recovery owns those.
+
+Liveness outcomes are auditable in `events.ndjson` as
+`provider.turn_liveness_timeout`, `provider.turn_liveness_retry`, and
+`provider.turn_liveness_give_up`. Exhausted retries fail the turn with a
+normalized `no_progress_timeout` error kind, distinct from the adapter-owned
+`timeout` kind that covers idle time after active work.
+
+## Sessions
+
+Provider session handles are opaque strings. Providers should preserve and
+return the SDK session handle when one exists, including on normalized failures
+where the SDK exposed a session before the failure.
+
+Neal persists handles separately for planner, coder, and reviewer work. Resume
+checks fail early if the configured provider role does not support session
+resume and a persisted handle must be resumed.
+
+## Structured Output
+
+Neal product control paths use `neal-json-block-v1`. Provider adapters transport
+assistant text, preserve session handles, normalize SDK errors, and delegate
+control-payload extraction, parsing, validation, bounded repair, telemetry, and
+normalized structured-output errors to Neal's shared runtime. The
+`generic-agentic` writer is the one exception: it consumes the same protocol
+spec (schema, validator, labels) but fulfills it through the AI SDK's native
+structured-output channel in a dedicated finalization turn, with no fenced-text
+transport — see [Generic Agentic Writer](#generic-agentic-writer).
+
+Coder adapters expose `runStructuredPrompt<TStructured>()` for Neal-owned
+structured coder decisions. That method receives a caller-owned
+`neal-json-block-v1` protocol spec, returns the typed `structured` object plus
+the provider `sessionHandle`, emits `structured_output_received` only after
+Neal validation succeeds, and normalizes missing structured control payloads as
+`structured_output_missing`.
+
+`runPrompt(..., outputSchema)` remains supported for compatibility with
+older raw coder harness coverage. `neal check` and Neal-owned coder decision
+rounds use `neal-json-block-v1` through `runStructuredPrompt()` rather than
+parsing provider JSON strings in round code.
+
+Neal's shared `neal-json-block-v1` runtime appends provider-neutral transport
+instructions requiring optional useful prose followed by exactly one final
+fenced `neal-json` JSON block. It then extracts, parses, validates, and repairs
+that control object with the caller-supplied schema label, schema, validator,
+and repair limit. Raw whole-response JSON objects are accepted only as a
+compatibility tolerance for older mocks and pre-migration paths; the prompt
+contract remains prose plus one final `neal-json` block. State-facing
+`structured_output_received` telemetry is emitted only after Neal validation
+succeeds.
+
+Anthropic Claude and OpenAI Codex structured coder and structured-advisor
+protocol calls do not pass SDK-native `outputFormat` or `outputSchema`. Those
+SDK-native surfaces are compatibility details for non-Neal raw provider calls,
+not the Neal product protocol. Invalid or missing local JSON can recover through
+a bounded repair turn. Repair turns are side-effect-free by prompt; Claude
+repair turns also omit repo tools and session resume, and Codex repair turns run
+through the most restrictive available streamed-turn options.
+
+## Telemetry
+
+Provider modules emit provider-neutral `ProviderRuntimeEvent` values through the
+turn's event sink. They do not call terminal diagnostic APIs or `RunLogger`
+directly.
+
+Normalized event types include:
+
+- `session_started`
+- `turn_started`
+- `turn_completed`
+- `tool_started`
+- `tool_progress`
+- `command_completed`
+- `file_changed`
+- `assistant_text`
+- `structured_output_received`
+- `usage_reported`
+- `provider_error`
+
+`src/neal/providers/telemetry.ts` adapts those events into `provider.*`
+`events.ndjson` records and low-level detail output. Command completion events
+carry enough metadata for verification summaries, including command, status,
+exit code, output length, working directory, and git head when available. Raw
+SDK details should remain contained under `providerData` when they are useful
+for debugging.
+
+## Errors
+
+Errors leaving provider adapters should be `NealProviderError` instances. Core
+round code should not import SDK-specific provider error classes.
+
+Normalized error kinds are:
+
+- `timeout`
+- `no_progress_timeout` (emitted by Neal's turn liveness supervisor, not by
+  adapters; see Turn Liveness above)
+- `api_error`
+- `structured_output_missing`
+- `structured_output_invalid`
+- `permission_denied`
+- `session_unavailable`
+- `provider_failed`
+- `unknown`
+
+Each normalized error carries the provider id, role, optional session handle,
+kind, retryability, and cause. Round code wraps normalized provider errors into
+round-level failures only when it needs round-specific context.
+
+## Status-Visible Errors
+
+Provider failures are visible to automation through `neal status --json` and
+`neal status --json --all` as `providerError`. Neal derives that summary from
+the latest `provider.provider_error` event when present, including timestamp,
+provider id, role, label, session handle, normalized kind, bounded message, and
+retryability. If a run failed before a provider event was available, status may
+fall back to the latest `phase.error` as an unclassified run error with
+`provider`, `role`, and `kind` set to `null`.
+
+`providerError` is classification metadata, not a raw provider transcript. It
+must not include SDK payloads, full prompts, provider `providerData`, full
+assistant text, raw command output, credentials, or environment dumps. Keep rich
+diagnostics in local support artifacts such as `events.ndjson` and
+`stderr.log`; public wrappers should use the bounded status summary.
+
+## Model Overrides
+
+Provider factories receive an optional model override from `agent.*.model`.
+`model: null` means Neal lets the provider choose its default model. A non-null
+model is accepted only when the provider role declares `supportsModelOverride`.
+
+Model selection stays provider-local after the registry passes the configured
+override into the adapter factory.
+
+## Reasoning Effort Overrides
+
+Each role accepts an optional reasoning-effort override from `agent.*.effort`.
+`effort: null` (or an omitted key) means Neal sends no effort option and the
+provider uses its default reasoning depth. A non-null effort is mapped to the
+closest provider-native option: OpenAI Codex receives
+`ThreadOptions.modelReasoningEffort` and Anthropic Claude receives
+`Options.effort`.
+
+Supported values are provider-specific:
+
+- `openai-codex`: `minimal`, `low`, `medium`, `high`, `xhigh`.
+- `anthropic-claude`: `low`, `medium`, `high`, `xhigh`, `max`.
+- `openai-compatible`: no supported values; any configured `effort` is rejected
+  with the standard effort config error.
+- `generic-agentic`: no supported values; any configured `effort` is rejected
+  with the standard effort config error.
+
+Effort support is declared per capability role. An effort value the configured
+provider does not support is rejected before a writer run starts or resumes with
+a role-specific config error that lists the supported values.
+
+Planner effort inheritance mirrors planner model inheritance: the planner
+inherits the coder effort only when `agent.planner.provider` is not configured
+explicitly and `agent.planner.effort` is omitted. If `agent.planner.provider`
+is set explicitly, an omitted `agent.planner.effort` resolves to provider
+default (`null`) rather than inheriting the coder effort, so set
+`agent.planner.effort` explicitly to override it.
+
+## OpenAI-Compatible Endpoints
+
+The `openai-compatible` provider lets the reviewer role run against any
+OpenAI-compatible Chat Completions endpoint (DeepSeek, OpenRouter, vLLM, and
+similar). It is API-only and covers structured-advisor work: reviewer rounds
+for scope review, plan review, support, final completion, provider check, and
+`neal review` findings adjudication.
+
+The adapter is implemented on the AI SDK's OpenAI-compatible chat provider —
+the same substrate the `generic-agentic` writer uses — with the external
+contract unchanged: same provider id, same config block, same chat-only
+capabilities, same normalized error kinds and retryability, same provider
+events. Gateway behaviors learned from live failures are preserved through a
+Neal-owned response interceptor: upstream errors embedded as an `error`
+object inside an HTTP 200 body keep their status-based retryability
+(OpenRouter wraps upstream 429s this way), and reasoning-model responses
+whose final text arrives in `message.reasoning` / `message.reasoning_content`
+instead of `message.content` fall back to that text. Usage events report the
+AI SDK's normalized shape (`inputTokens` / `outputTokens` / `totalTokens`
+plus detail fields), with the raw response usage object preserved under
+`usage.raw`.
+
+Role restrictions and behavior:
+
+- Structured-advisor/reviewer roles only. There is no coder or planner
+  support; selecting `openai-compatible` for those roles fails the capability
+  check with a clear error before any run starts.
+- No tool access of any kind (`read`, `write`, and `shell` are all declared
+  false). Neal inlines the review context — the full diff, plan document
+  content, review history, and run artifacts, with per-section truncation
+  caps — directly into reviewer prompts, and reviewer prompts render the
+  `no-read` review doctrine mode (see
+  [Review Doctrine Access Modes](#review-doctrine-access-modes)). The
+  tradeoff: an inline-context reviewer cannot independently run verification
+  commands or read beyond the inlined sections, so review quality depends on
+  the inlined context. For tool-calling models, the `generic-agentic`
+  reviewer path avoids that tradeoff; see
+  [Generic Agentic Writer](#generic-agentic-writer).
+- No session resume. The adapter never returns a resumable session handle, so
+  no reviewer session state is persisted for it.
+- No `effort` support. Any configured `agent.reviewer.effort` for this
+  provider is rejected with the standard effort config error.
+- Structured output uses Neal's `neal-json-block-v1` protocol and bounded
+  repair loop, not provider-specific `response_format` or strict JSON schema.
+- Requests are non-streaming Chat Completions; `neal.inactivity_timeout_ms`
+  acts as the whole-request timeout. Model quality, rate limits, and exact API
+  behavior vary by upstream provider.
+
+### Configuration
+
+Add a `providers.openai_compatible` block (repo `config.yml` overrides
+`~/.neal/config.yml`, matching normal config precedence) and point the
+reviewer role at the provider. A worked DeepSeek example:
+
+```yaml
+providers:
+  openai_compatible:
+    base_url: https://api.deepseek.com
+    api_key_env: DEEPSEEK_API_KEY
+    default_model: deepseek-chat
+
+agent:
+  coder:
+    provider: openai-codex
+    model: null
+  reviewer:
+    provider: openai-compatible
+    model: deepseek-chat
+```
+
+Settings resolve config-first with environment fallbacks:
+
+- `base_url`: `providers.openai_compatible.base_url`, else
+  `OPENAI_COMPATIBLE_BASE_URL`. Required.
+- `api_key_env`: `providers.openai_compatible.api_key_env`, else the default
+  `OPENAI_COMPATIBLE_API_KEY`. The API key value is read from that named
+  environment variable; Neal never stores the key itself.
+- model: the role-level `agent.reviewer.model` override, else
+  `providers.openai_compatible.default_model`, else `OPENAI_COMPATIBLE_MODEL`.
+  One of these is required.
+- `headers`: optional string-to-string map of extra HTTP headers (useful for
+  OpenRouter attribution headers).
+
+`neal setup` offers `openai-compatible` for the reviewer role only and prints
+guidance when the base URL, API key, or model is unresolved. `neal setup`
+detection reports which config keys or environment variables are missing
+without making network calls.
+
+### Live Smoke Check (optional)
+
+The default test suite never requires live credentials or network access. To
+verify a real endpoint end to end, set credentials and run `neal check` with
+the reviewer role configured for `openai-compatible` — the `provider-check`
+structured round exercises the adapter against the live endpoint:
+
+```sh
+OPENAI_COMPATIBLE_BASE_URL=https://api.deepseek.com \
+OPENAI_COMPATIBLE_API_KEY=... \
+OPENAI_COMPATIBLE_MODEL=deepseek-chat \
+pnpm start -- check
+```
+
+## Generic Agentic Writer
+
+The `generic-agentic` provider runs the coder role (and the inherited planner
+role) against any OpenAI-compatible Chat Completions endpoint with a strong
+tool-calling model (OpenRouter, vLLM, DeepSeek, and similar). Unlike the
+API-only `openai-compatible` reviewer adapter, this provider is a real writer:
+Neal owns the agentic loop (one model turn per request, with a Neal-owned
+outer loop over the message history) and supplies its own tool set —
+`read_file`, `write_file`, `edit_file`, `list_dir`, `grep`, and `run` — so any
+endpoint whose model can call tools reliably can serve as the coder, and,
+through a read-only subset of the same tools, as the reviewer.
+
+Because endpoint quality varies, qualify a generic-agentic model with
+[`neal compat`](compat.md) before trusting it with real work: it drives the
+candidate through complete neal runs against trivial bundled fixtures and emits
+a binary PASS/FAIL per (model, role). `neal check` proves only connectivity and
+basic protocol; `neal compat` proves the full loop.
+
+Role support and behavior:
+
+- Coder-first. The coder capability role is read, write, and shell capable;
+  the planner inherits the coder provider unless configured explicitly.
+- Tool-capable reviewer. The structured-advisor role runs the same
+  Neal-owned loop over a read-only toolset — `read_file`, `list_dir`,
+  `grep`, and the read-only `git_diff` commit-range inspector — so a generic
+  reviewer inspects the repository directly under the `read-only` review
+  doctrine mode (see
+  [Review Doctrine Access Modes](#review-doctrine-access-modes)) instead of
+  receiving Neal-inlined context. `git_diff` is a Neal-owned fixed-argv git
+  query (never a shell string) that gives the reviewer actual commit-range
+  visibility, including deletions and renames that head-state file reads
+  cannot reveal. After the read-tool loop completes with a zero-tool-call
+  turn, the structured payload is requested in a single dedicated
+  finalization turn that carries no tools. The same adapter also serves the
+  final-completion summary gate when `generic-agentic` is the coder.
+- No session resume (`supportsSessionResume: false` on both roles). The
+  adapter never persists a provider session handle, so `neal resume` after an
+  interruption or failure restarts the interrupted scope from scratch in a
+  fresh session rather than resuming mid-conversation. Already-accepted
+  scopes stay committed; only the in-flight scope is redone. Top-level
+  plan-refinement revision rounds likewise start a fresh planner session per
+  round instead of resuming the planning conversation.
+- Step caps: each coder prompt's tool loop is bounded by the exported
+  `GENERIC_AGENTIC_MAX_STEPS` constant (currently `48` model turns per
+  prompt); structured-advisor/reviewer rounds use the smaller exported
+  `GENERIC_AGENTIC_ADVISOR_MAX_STEPS` constant (currently `24` — reviews are
+  bounded inspections, not implementations). Reaching either cap fails the
+  attempt with a non-retryable `provider_failed` error naming the cap. There
+  are no config knobs for the caps.
+- Reviewer telemetry: advisor rounds report cumulative per-tool call and
+  error counts plus a `steps` count (model turns consumed) under
+  `providerData` on `turn_completed` / `usage_reported` events, so
+  tool-turns-per-review is auditable from `events.ndjson` when qualifying a
+  model for reviewer duty.
+- No `effort` support. Any configured `effort` for this provider is rejected
+  with the standard effort config error.
+- Structured output is SDK-native. After the tool loop's normal
+  zero-tool-call completion turn, the adapter makes exactly one dedicated
+  finalization turn (no tools) through the AI SDK's `Output.object`
+  structured-output channel and validates the result against the protocol
+  schema. There is no fenced-JSON text protocol on this provider and no
+  second chance for a malformed payload: a finalization failure is a single
+  non-retryable error — kind `structured_output_missing` when the model
+  produced no parseable object, or `structured_output_invalid` when the
+  object failed validation — with a truncated excerpt of the rejected text
+  preserved under the `provider_error` event's `providerData.diagnostic`, so
+  failed runs stay classifiable. Tool inputs are likewise strict: arguments
+  must match the tool's schema as sent, with no coercion of stringified
+  JSON. This failure taxonomy is the qualification signal for candidate
+  models — a model that cannot pass `neal check` on this provider is not
+  pool-eligible.
+- Transient API failures (408/429/5xx, network errors, and empty
+  HTTP-200 responses) are retried with bounded backoff and surfaced as
+  `api_retry` progress events, matching the `openai-compatible` adapter's
+  behavior.
+
+Trust level is identical to the vendor writer providers: the `run` tool
+executes arbitrary shell commands in the scope working tree with no sandbox.
+The path jail on file-tool arguments keeps `read_file`, `write_file`,
+`edit_file`, `list_dir`, and `grep` inside the repository (including through
+symlinks), but it does not contain what `run` can do. Apply the same
+disposable-checkout guidance as for the other writer providers.
+Structured-advisor rounds never receive `write_file`, `edit_file`, or `run`;
+the read-only toolset is jailed the same way.
+
+Choosing a reviewer adapter for generic endpoints: prefer `generic-agentic`
+when the endpoint's model calls tools reliably — the reviewer reads the
+actual repository and commit range with bounded, targeted tool calls instead
+of judging a truncation-capped inlined diff, and reviewer prompts stay small.
+Prefer `openai-compatible` for genuinely chat-only endpoints or models whose
+tool calling is unreliable; the inline-context path remains correct and fully
+supported.
+
+Model guidance: use a paid tool-calling slug for coder duty. Rate-limited
+`:free` pools are acceptable for reviewer-only use but are not suitable as
+coders. Model qualification runs and a tested-models table are future work;
+until that lands, treat models other than `qwen/qwen3-coder` (validated
+end-to-end as the coder) and `openai/gpt-oss-120b` (validated live as the
+read-only reviewer and as the inline-context reviewer) as unqualified and
+trial them on a disposable project first.
+
+### Configuration
+
+Settings reuse the `providers.openai_compatible` block — there is no separate
+`providers.generic_agentic` config surface — with the same config-first,
+environment-fallback resolution documented in
+[OpenAI-Compatible Endpoints](#openai-compatible-endpoints). A worked
+OpenRouter example:
+
+```yaml
+providers:
+  openai_compatible:
+    base_url: https://openrouter.ai/api/v1
+    api_key_env: OPENROUTER_API_KEY
+    default_model: qwen/qwen3-coder
+
+agent:
+  coder:
+    provider: generic-agentic
+    model: null
+  reviewer:
+    provider: anthropic-claude
+    model: null
+```
+
+The planner inherits the coder provider unless configured explicitly, so this
+config routes planning through `generic-agentic` too. Coder model precedence
+is `agent.coder.model`, else `providers.openai_compatible.default_model`,
+else `OPENAI_COMPATIBLE_MODEL`; one of these is required. Structured-advisor
+rounds additionally honor a Neal-internal round-level model override first,
+matching the `openai-compatible` adapter.
+
+## Adding A Built-In Provider
+
+To add another built-in provider:
+
+1. Implement a provider module under `src/neal/providers/`.
+2. Export a `NealProviderDefinition`.
+3. Register the definition in `src/neal/providers/registry.ts`.
+4. Map SDK sessions and resume handles to opaque Neal handles.
+5. Map SDK stream or message events to `ProviderRuntimeEvent` values.
+6. Normalize SDK errors to `NealProviderError`.
+7. Add focused tests for event mapping, capabilities, Neal structured control
+   protocol behavior, session handles, and normalized errors.
+8. Document SDK prerequisites, environment assumptions, supported roles,
+   capabilities, and limitations.
+
+Use `test/helpers/fake-provider.ts` for registry and capability tests that do
+not need a real SDK. SDK adapter tests should stay focused on provider-specific
+event collection, structured-output parsing, retry behavior, and error
+normalization.
+
+## SDK Prerequisites
+
+Provider documentation should state the SDK package, required credentials or
+login state, model assumptions, filesystem/tool permission assumptions, and any
+environment variables the SDK needs.
+
+Current built-in writer providers run with broad local permissions:
+
+- OpenAI Codex uses `approvalPolicy: never` and
+  `sandboxMode: danger-full-access`.
+- Anthropic Claude uses `permissionMode: bypassPermissions`.
+- OpenAI-Compatible is the exception: it makes HTTP API calls only and has no
+  local filesystem or shell access.
+- Generic Agentic makes HTTP API calls for model turns but executes Neal-owned
+  tools locally; the coder role's `run` tool executes shell commands with no
+  sandbox, matching the vendor writers' trust level. Structured-advisor
+  rounds execute only the read-only toolset locally.
+
+Those settings are part of current writer-run behavior. Do not narrow or widen
+them as part of provider registration unless a separate product change requires
+it.
+
+## Review Boundary
+
+Public `neal review` uses a separate read-only findings loop:
+
+- `src/neal/review-findings/provider.ts`
+
+The default adapter uses the configured coder provider to draft structured
+findings and the configured reviewer structured-advisor adapter to adjudicate
+them. The command is still not a writer-run mode: it does not create
+`RUN_STATE.json`, does not mutate `.neal/current.json` or queue pointers, and
+writes isolated artifacts under `.neal/reviews/<review-id>/`.
+
+Two distinct read-only guarantees apply here, and they should not be conflated:
+
+- The provider-capability invariant (see
+  [The Read-Only Reviewer Invariant](#the-read-only-reviewer-invariant)):
+  every supported `structured-advisor` capability has `write: false` and
+  `shell: false`, so a writer-run reviewer/structured-advisor round cannot
+  write or run shell by capability — this holds for both writer runs and
+  `neal review`.
+- The `neal review` command's additional artifact-boundary guard: the command
+  checks protected writer state and worktree changes after provider rounds and
+  fails if anything outside its review artifacts changed. This post-round guard
+  is owned by the `neal review` command flow, not by a provider capability, and
+  is specific to `neal review`; a writer run does not perform this artifact
+  diff.
+
+So the capability invariant guarantees reviewers never write or run shell in
+any mode, while `neal review` adds its own command-level enforcement on top.
+Do not treat the `neal review` artifact-boundary guard as a provider capability,
+and do not assume a writer run performs that post-round artifact check.