# Phase 3: OpenAI Provider and Coding Tools

## Objective and prerequisites

Prove the kernel's public model and tool seams with independent production
modules: OpenAI Responses streaming plus bounded read, replace/write, and
process execution. This phase requires immutable kernel contracts, typed
provider errors, capability-aware dispatch, and phase 1 auto-configuration.

## Provider contracts

- Pin `github.com/openai/openai-go/v3 v3.50.0` exactly.
- Translate provider-neutral requests into Responses API input without exposing
  the raw SDK client as public API. The request owns the selected model.
- Support text deltas, finalized function calls, usage, cancellation, refusal or
  typed failure, and bounded safe metadata. A completed response is the
  authoritative source of finalized tool call IDs and arguments.
- Provider startup errors and stream receive errors carry a bounded typed
  `model.Problem`. The kernel—not the adapter—computes whether any stream item
  was observed, so a failure after partial output is never retried as pristine.
- Retry only errors known to occur before streaming begins. Idempotency keys are
  stable derivatives of host operation IDs and reveal no prompt or tool data.
- Configuration validates timeouts, base URL, organization/project IDs, and
  credentials. Secret values are redacted from formatting, errors, events,
  manifests, generated source, and test artifacts.
- The starter is a fallback `model.Provider`; an application-owned normal or
  primary bean follows normal Spice DI replacement rules.

## Coding-tool contracts

- `read` accepts a validated relative path plus paging bounds, uses an anchored
  root, reports UTF-8 or base64, and returns a hash when a complete file is read.
- `replace` creates exclusively or performs a stale-protected atomic file
  replacement using an expected SHA-256. It serializes commits within the bean,
  rechecks immediately before rename, and explicitly does **not** promise a
  cross-process atomic compare-and-swap primitive.
- A replacement reports `committed` separately from `durable`; a post-commit
  file/directory sync failure is an uncertain-durability result, not a claim
  that no mutation occurred.
- `shell` executes discrete argv without a shell, from a validated worktree-
  selected starting directory. It is not filesystem containment: the child has
  the user's full process, network, filesystem, and allowlisted-environment
  privileges.
- Shell output is count/byte bounded, binary-safe, cancellable, and time bounded.
  Unix process groups and Windows kill-on-close Job Objects are used; inability
  to confirm tree termination is surfaced.
- Every tool publishes exact capabilities and uses the canonical dispatcher.
  First-run/help text warns that no permission or sandbox extension is active.

## Implementation slices

1. Implement fake-source provider translation and exhaustive offline tests.
2. Add redacted typed configuration, starter manifest, and explicit
   `/autoconfigure` package.
3. Add an opt-in live test requiring an explicit environment switch and secret;
   ordinary verification must neither run it nor contact the network.
4. Implement anchored read, atomic replacement, and process tools with immutable
   definitions and fallback beans.
5. Add dependency, license, maintenance, retry, observability, and security
   reviews in each repository.
6. Pin immutable core pseudo/tag versions, remove local `replace`, regenerate
   vendor data, and prove isolated offline verification.
7. Add a generated application acceptance flow: streamed text, one compiled
   tool call, continuation, final text, cancellation, and secret-redaction scan.

## Exclusions

The provider module does not select retry policy for partially observed streams,
persist conversations, or own global clients. Coding tools do not implement
approval, sandbox, Git policy, remote execution, or hidden path/network
restrictions. Those are later dispatcher decorators or alternate tool beans.

## Verification

- Provider tests cover malformed/unknown events, partial streams, duplicate or
  undeclared calls, usage, metadata bounds, startup/receive cancellation,
  ambiguous retry, redaction, and stream-close failures.
- Tool tests cover traversal, links, device/special files, invalid UTF-8, paging,
  stale hashes, create races, cancellation before commit, uncertain durability,
  output truncation, process start/exit/timeout, descendants, and environment
  allowlisting on Windows and Unix.
- Shuffled race tests prove singleton bean concurrency. Fuzz smoke targets JSON
  argument decoding and provider event translation.
- `make verify` includes isolated tools-module security, exact vendor contents,
  and at least 85% handwritten product coverage.

## Performance and completion evidence

Local adapter translation targets sub-millisecond per event outside SDK/network
latency. Cooperative process cancellation targets p95 below 50 ms before the
configured grace interval; forced tree cleanup has an explicit bounded deadline.

Status is **in progress**. The hardened core is pinned for active provider and
coding-tool implementations. This phase closes only after both repositories
push green standalone commits and the generated cross-repository vertical flow
passes.