agent-harness 0.37.5 → 0.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 689dc0db60fba2154368f84887018123219d2933eabf037b8592bd0c4ab4c6a6
-  data.tar.gz: 1a66d12fde96441a8220656cb49ef1b742372c12de8873f6b5676a6f8540dc6e
+  metadata.gz: 6b6b9b84a3074d82a44dd35a6b377628c64cfa01958ca5c41ec910b694375fcf
+  data.tar.gz: 8069427d9a79624deba026984490a5f25cf97df7364c6d78b44c2a43aef773c6
 SHA512:
-  metadata.gz: c966600212a4920c975efa9f7155b64c31aa8129a524eceedf993acbc0d3d099c3ef59cddaf1f23d51edafdad9b9e88a38e5fb18e8bcf36322beecb4f37eb8d7
-  data.tar.gz: 05cd073a1878124085ced27da8b297dc67e84ccc900ef9e38e1d2893b1de4f3b72a4c11e516b3575d9b6bcf66eaf0c1976bf8b8ee5ee94fc54c17e0f8f16e42e
+  metadata.gz: cad34514f544dcf13a470afbb7cbdde82269246ee16d97319e3e6f33afd2e663b0625fd2f088bc4c68ef491676ac3c5cfc80e6bc3ba5a030fbda1abbe9a04cf7
+  data.tar.gz: 48fd85599fca1ae94fe13e433d4a69d1ab5bd8ce4c9c8feab6388c79c2d48c5314467cba8c4fcb277662c1aea20f53206b35fef6cad0a82ef82618249a80a883

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.37.5"
+  ".": "0.39.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,20 @@
 * add runner model compatibility contract (`AgentHarness.model_compatibility`) with structured `ModelCompatibility::Result` outcomes. Codex exposes static facts for CLI-gated models (e.g. `gpt-5.5` requires Codex CLI `>= 0.116.0`), a baseline supported-model list, supported auth modes, and a `DEFAULT_COMPATIBLE_MODEL_ID` fallback so downstream orchestrators can validate tier/model assignments before scheduling agent runs ([#259](https://github.com/viamin/agent-harness/issues/259)).
 * **auth:** add provider-owned PKCE code-exchange API for Claude OAuth (`AgentHarness::Authentication.exchange_code`). Takes an authorization code plus PKCE verifier (and `redirect_uri`/`client_id`), posts an `authorization_code` grant to the Claude token endpoint, and persists the resulting access/refresh tokens in the native `claudeAiOauth` shape. Adds `exchange_code_supported?` and a `code_exchange` key to `auth_capabilities` ([#266](https://github.com/viamin/agent-harness/issues/266)).
 
+## [0.39.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.38.0...agent-harness/v0.39.0) (2026-09-25)
+
+
+### Features
+
+* design: Define the Provider-Neutral API Execution Contract (RDR-072) ([#438](https://github.com/viamin/agent-harness/issues/438)) ([ae2fc6b](https://github.com/viamin/agent-harness/commit/ae2fc6bafad54ac35bb9d30a32d253c68a7396f2))
+
+## [0.38.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.37.5...agent-harness/v0.38.0) (2026-09-24)
+
+
+### Features
+
+* **codex:** expose account-local discovery for container recovery ([#428](https://github.com/viamin/agent-harness/issues/428)) ([a67c11f](https://github.com/viamin/agent-harness/commit/a67c11f46aaf99cd440cbb69edbd3272f3ed9312))
+
 ## [0.37.5](https://github.com/viamin/agent-harness/compare/agent-harness/v0.37.4...agent-harness/v0.37.5) (2026-09-21)
 
 

data/README.md

@@ -419,6 +419,24 @@ result.fallback_model_id     # => "gpt-5.2-codex"
 result.source                # => :static_contract
 ```
 
+For account-local Codex discovery, use the same executor and credential
+environment as execution:
+
+```ruby
+provider = AgentHarness::Providers::Codex.new(executor: container_executor)
+discovery = provider.discover_available_models(env: subscription_env, timeout: 15)
+discovery.models                 # normalized visible entries from model/list
+discovery.recommended_model_id   # provider default, not proof of execution
+```
+
+This method performs a fresh, paginated app-server exchange within the supplied
+execution context. It supports execute-only container transports using Node
+(already required by the Codex npm installation). It never changes auth mode or
+selects a model on the caller's behalf. Apply project policy, verify the chosen
+model with `smoke_test`, and persist successful evidence in the calling system.
+`classify_model_rejection_from_result(stdout:, stderr:)` excludes ordinary
+assistant/tool stdout from rejection classification.
+
 Outcomes follow three explicit shapes:
 
 - **Supported** — `result.supported?` is `true`. The runner contract
@@ -720,6 +738,12 @@ Health checks run five steps per provider: registration, CLI availability, authe
 
 ## Development
 
+The proposed provider-neutral API execution boundary for embeddings, chat,
+structured output, usage, and optional persistence is documented in the
+[Provider-Neutral API Execution Contract](docs/provider-neutral-api-execution-contract.md).
+It is a docs-only design boundary; capability support requires the release
+evidence described there.
+
 ```bash
 # Install dependencies
 bin/setup

data/docs/provider-neutral-api-execution-contract.md

@@ -0,0 +1,532 @@
+# Provider-Neutral API Execution Contract
+
+This document records the design investigation for
+[RDR-072](https://github.com/viamin/paid/blob/01672a9992853e89bcbd272b720ac9f1da73cba0/docs/rdrs/RDR-072-api-conversation-delegation.md).
+It is the upstream contract for incremental embedding, chat, structured-output,
+usage, and optional conversation-persistence work.
+
+## Status and rollout boundary
+
+This is a design contract, not a claim that the described API is implemented.
+RDR-072's rollout guard is **docs-only now**, so this change adds no runtime
+behavior or dependency. Each capability below needs its own failing-first
+contract tests, implementation, release evidence, and downstream adoption
+evidence before a caller enables it.
+
+Existing CLI and subscription behavior remains the default. Existing
+`TextTransport`, `OpenAICompatibleTransport`, `Conversation`, and `Response`
+interfaces remain available, but they do not yet satisfy this contract. A
+caller must not infer support from a gem version or issue closure.
+
+Normative words such as MUST and MUST NOT describe the future public boundary.
+
+## Ownership boundary
+
+AgentHarness owns protocol translation and one bounded provider request:
+
+- capability discovery and explicit unsupported outcomes;
+- provider-specific request and response translation;
+- request retries within caller-supplied limits;
+- normalized stream events, results, errors, and attempt reports; and
+- stable attempt and tool-call identities at its public boundary.
+
+The caller owns application authority and durable policy:
+
+- tenant and actor identity, authorization, and visible tools;
+- candidate order, credentials, allowed models, and fallback notices;
+- budgets, cancellation initiation, runner changes, and workflow recovery;
+- durable usage attribution and idempotent ingestion of attempt reports;
+- tool confirmation and side-effect reconciliation; and
+- application conversation/message identity and audit records.
+
+The harness MUST NOT select an unlisted fallback, borrow global credentials,
+change authentication mode, execute a tool, or replay a completed tool result.
+Keeping the caller's chat loop over this normalized transport is an acceptable
+final architecture.
+
+## Common execution request
+
+All operations use an immutable, request-local configuration. The eventual
+Ruby API MAY use value objects rather than hashes, but it MUST expose these
+semantics:
+
+```ruby
+request = {
+  request_id: "paid-generation-018f...", # caller-generated, stable on redelivery
+  operation: :chat,                       # :chat, :embedding, or :schema
+  candidates: [                           # ordered; first entry is initial
+    {
+      provider: :anthropic,
+      model: "claude-sonnet-4-5",
+      protocol: :messages,                # optional verified protocol
+      authentication_mode: :api_key,
+      endpoint: "https://llm-proxy.example/v1",
+      headers: {"X-Tenant-Route" => "tenant-123"},
+      credentials: {api_key: anthropic_secret}
+    },
+    {
+      provider: :openai,
+      model: "gpt-5",
+      protocol: :responses,
+      authentication_mode: :api_key,
+      endpoint: "https://api.openai.com/v1",
+      headers: {},
+      credentials: {api_key: openai_secret}
+    }
+  ],
+  fallback: {on_error_categories: [:transient]},
+  timeout: {connect_seconds: 5, read_seconds: 60},
+  retry: {max_attempts: 3, base_delay_seconds: 0.25, max_delay_seconds: 2},
+  cancellation: cancellation_token,
+  metadata: {tenant_id: "tenant-123", workflow_id: "workflow-456"}
+}
+```
+
+`candidates` MUST contain at least one complete candidate record. Its first
+entry is the initial candidate; later entries are the only authorized fallback
+order. A request that does not authorize fallback supplies a one-entry array.
+`fallback.on_error_categories` is the caller-selected allowlist of error
+categories that permit advancing to the next entry; an absent or empty
+allowlist disables fallback. Candidate records, their order, and the allowlist
+are immutable for the lifetime of the request. The observer described below is
+a request-local callback or equivalent API argument because callbacks are not
+part of a serializable request document.
+
+`request_id` identifies one logical operation. Every physical outbound request
+gets a distinct `attempt_id`. Redelivering an already reported attempt retains
+its `attempt_id`; initiating another outbound request does not.
+
+Credentials, endpoint, headers, timeouts, retry limits, and cancellation are
+request-local. Implementations MUST prevent concurrent requests from observing
+one another's credentials or headers. They MUST reject reserved header
+overrides that would conflict with the selected protocol's authentication.
+Logs and errors MUST NOT contain credentials, authorization headers, message
+bodies, tool arguments, or full provider responses.
+
+The selected candidate's provider, model, protocol, endpoint, and authentication
+mode MUST be the values actually used. The harness MUST return a configuration
+or unsupported outcome instead of silently substituting any of them.
+
+## Capability discovery and unsupported outcomes
+
+Support is declared per operation, provider, protocol, model when known, and
+authentication mode. It is not a single provider-wide Boolean. The discovery
+result has one of three states:
+
+- `supported`: the requested combination is verified;
+- `unsupported`: it is known not to work, with a stable reason; or
+- `unknown`: it has not been verified and MUST NOT be routed as supported.
+
+Stable unsupported reasons initially include:
+
+- `operation_not_supported`;
+- `protocol_not_supported`;
+- `authentication_mode_not_supported`;
+- `custom_endpoint_not_supported`;
+- `custom_headers_not_supported`;
+- `streaming_not_supported`;
+- `tools_not_supported`;
+- `structured_output_not_supported`; and
+- `state_restoration_not_supported`.
+
+An unsupported result is a normal, non-retryable outcome carrying the requested
+scope and reason. It is not a generic provider failure. Callers MAY choose
+another candidate only from their own ordered list.
+
+## Normalized chat contract
+
+### Messages
+
+The input is an ordered array. Each message has a stable caller-owned `id`, one
+of `system`, `user`, `assistant`, or `tool` as its `role`, and an ordered
+`content` array. Content parts initially support `text`; unimplemented media
+parts produce an explicit unsupported outcome. Assistant messages MAY contain
+tool calls. Tool messages MUST reference exactly one `tool_call_id`.
+
+Provider-specific wire roles, system-message placement, and content block
+shapes stay behind the harness boundary. The harness MUST preserve ordering,
+empty assistant text accompanying tool calls, and unknown versus absent data.
+
+### Tools
+
+Tool definitions contain a caller-owned name, description, and JSON Schema
+input definition. A normalized tool call contains:
+
+```ruby
+{
+  id: "toolcall_018f...",       # stable harness ID
+  provider_id: "call_abc",      # optional provider correlation only
+  name: "search_documents",
+  arguments_json: "{\"query\":\"Ruby\"}"
+}
+```
+
+The stable `id` is generated before the call is exposed or persisted and MUST
+survive export/import. `provider_id` is not a durable application identifier.
+Arguments remain JSON text until parsing succeeds; malformed arguments produce
+a classified parse failure and are never executed by the harness. Tool results
+reference the stable ID. Redelivery or restoration MUST skip a tool call when a
+completed result for that ID exists.
+
+The transport never decides approval and never executes application tools.
+
+### Streaming
+
+The stream is ordered and contains these normalized event types:
+
+- `response_started` with request and attempt identity;
+- `text_delta` with appended text;
+- `tool_call_started`, `tool_call_delta`, and `tool_call_completed`;
+- `usage_updated` when defensible cumulative or delta usage is available;
+- `response_completed` with the final normalized result; and
+- `response_failed` or `response_cancelled` with the partial result.
+
+Every event carries `request_id`, `attempt_id`, and a monotonically increasing
+`sequence`. A terminal event occurs exactly once per attempt. Callback failure
+requests cancellation and surfaces as a caller error; it MUST NOT be converted
+to provider success.
+
+If a stream ends after emitting content, the terminal result has
+`status: :partial`, retains received text and completed tool calls, and carries
+the classified error. Incomplete tool calls are marked incomplete and MUST NOT
+be executed. A partial attempt is never transparently retried: already emitted
+content cannot be withdrawn. The caller must explicitly decide whether a new
+attempt is safe and how to represent the abandoned partial message.
+
+### Result
+
+A completed chat or schema result contains:
+
+```ruby
+{
+  request_id: "paid-generation-018f...",
+  status: :succeeded, # :succeeded, :partial, :failed, or :cancelled
+  provider: :anthropic,
+  model: "claude-sonnet-4-5",
+  authentication_mode: :api_key,
+  content: "...",
+  parsed: nil,
+  tool_calls: [],
+  finish_reason: :stop,
+  attempts: [],
+  usage: {input_tokens: 12, output_tokens: 8, total_tokens: 20},
+  provider_request_id: nil,
+  error: nil
+}
+```
+
+`usage` aggregates only the attached attempt reports. Missing provider values
+remain `nil`; they are not coerced to zero. `provider_request_id` is optional
+diagnostic correlation and is not the accounting identity.
+
+## Structured-output contract
+
+A schema operation adds a JSON Schema and optional schema name to the chat
+request. The capability check MUST cover the selected provider/model/protocol
+and requested schema mode. JSON-only mode is not equivalent to schema-enforced
+output and MUST be reported separately.
+
+On success, `content` preserves provider JSON text and `parsed` contains the
+parsed Ruby value. Invalid JSON or schema mismatch is a classified,
+non-transient result with the original text retained. The harness MUST NOT
+silently strip fences, repair content, issue a second model call, or switch to
+a different credential to make parsing succeed.
+
+## Embedding contract
+
+An embedding request supplies one string or an ordered array of strings,
+provider/model candidate, and optional dimensions. Its result preserves input
+order and contains dense vectors, the model actually used, per-attempt usage,
+and optional provider request correlation. One input returns one vector;
+multiple inputs return an equal-length vector array.
+
+Empty batches, unsupported dimensions, unsupported input media, and batch-size
+limits are explicit configuration or unsupported outcomes. The first release
+need not cover multimodal or provider-side batch APIs. Vector persistence and
+similarity search remain caller responsibilities.
+
+## Attempts, usage, retries, and cancellation
+
+Each physical provider request produces an attempt report, including failed and
+cancelled attempts:
+
+```ruby
+{
+  attempt_id: "attempt_018f...",
+  request_id: "paid-generation-018f...",
+  number: 2,
+  provider: :anthropic,
+  model: "claude-sonnet-4-5",
+  status: :failed,
+  started_at: "2026-09-25T12:00:00Z",
+  finished_at: "2026-09-25T12:00:01Z",
+  usage: {input_tokens: nil, output_tokens: nil, total_tokens: nil},
+  cost: nil,
+  provider_reported: false,
+  error: {category: :transient, code: :service_unavailable}
+}
+```
+
+Attempt reports are delivered both with the final result and through an
+observer so durable accounting can persist an attempt even when no message is
+created. Callers deduplicate on `attempt_id`. Cost identifies its source as
+provider-reported or harness-estimated; unknown cost remains `nil`.
+
+Only errors classified `transient` are eligible for bounded request retry:
+connection failure, timeout before a partial stream, rate limit, server error,
+service unavailable, and overload. Authentication, authorization, billing,
+invalid request, unsupported capability, invalid schema, context length,
+configuration, and cancellation are non-retryable.
+
+The supplied `max_attempts` includes the first outbound request and is the total
+physical-attempt budget across all candidates; changing candidates does not
+reset it. It MUST be a positive integer; the harness rejects zero, negative, or
+non-integer values as configuration errors before making an outbound request.
+Delay and provider `retry-after` handling remain within the supplied bounds.
+Cancellation is checked before an attempt, during backoff, while reading a
+stream, and before returning success. It stops further attempts and returns a
+cancelled terminal outcome with any partial usage. Cancellation does not prove
+that the provider stopped processing or billing the request.
+
+The harness owns the complete attempt sequence; there is exactly one retry
+owner. RubyLLM's Faraday retry middleware resends the current candidate inside
+the transport before a classified error can return to the harness, so
+middleware-driven retries cannot honor the fallback-first order below and would
+spend the shared budget on one candidate invisibly to the observer. An adapter
+backed by RubyLLM MUST therefore disable its retry middleware with
+`max_retries: 0`, overriding the default three retries, so that one adapter
+call performs exactly one physical outbound request. The harness then issues
+one adapter call per attempt — initial, retry, or fallback — and applies the
+shared `max_attempts` budget, cancellation checks, backoff, and provider
+`retry-after` between calls. No component may retry beneath the harness, and
+the harness MUST NOT delegate this sequencing to middleware or another nested
+loop. Existing conductor retry/provider switching is not part of an API
+request's internal retry budget and MUST be disabled or bypassed for a
+migrated scope.
+
+## Caller-controlled fallback
+
+Fallback candidates are the entries after the first entry in the request's
+ordered `candidates` array. Each is a complete request-local candidate record,
+including credentials and endpoint/header overrides. A candidate change is a
+new caller-authorized selection, not a hidden retry. Before advancing, the
+harness invokes the request-local observer with the current and next candidate
+identities and the classified error, so the caller can cancel the change or
+issue a notice. The harness reports every candidate attempt.
+
+Fallback is allowed only for caller-selected error categories. It never occurs
+after a partial stream without a new explicit caller decision, never crosses
+authentication modes implicitly, and never replays completed tools. The
+harness MUST NOT use RubyLLM global fallback or global credential configuration
+where it could exceed this list or leak request-local configuration.
+
+Fallback takes precedence over retry when both are eligible. After a failed
+attempt, the harness MUST apply this order:
+
+1. Stop if cancellation was requested or any partial stream was exposed.
+2. If the budget has capacity, the error category is in
+   `fallback.on_error_categories`, and another candidate remains, notify the
+   observer and advance to that candidate.
+3. Otherwise, retry the current candidate only when the error is retryable and
+   the shared `max_attempts` budget has capacity.
+4. Otherwise, return the terminal error.
+
+The outbound request after either advancing or retrying consumes one physical
+attempt from the same budget. Candidates are never revisited, and a failed
+observer notification or observer cancellation stops before that request.
+Consequently, the example request attempts Anthropic once and then OpenAI after
+an eligible `transient` failure; only OpenAI can consume the remaining
+same-candidate retry budget.
+
+## Error contract
+
+Every terminal error exposes a stable category and code, retry eligibility,
+provider/model identity, optional sanitized status and request ID, and partial
+result/usage where available. Categories are:
+
+| Category | Examples | Request retry |
+| --- | --- | --- |
+| `transient` | timeout, connection failure, 429, 5xx, overload | bounded |
+| `authentication` | missing or rejected credential | never |
+| `authorization` | credential lacks access | never |
+| `billing` | inactive billing account or payment required | never |
+| `configuration` | invalid endpoint/header/model or local configuration | never |
+| `invalid_request` | malformed or semantically invalid provider request | never |
+| `context_length` | request exceeds the model context window | never |
+| `unsupported` | operation or option not implemented | never |
+| `invalid_response` | malformed JSON, schema/tool parse failure | never |
+| `cancelled` | caller cancellation | never |
+| `caller` | callback or local input failure | never |
+| `unknown` | provider failure that cannot be classified confidently | never |
+
+Adapters MUST use the following category and code mappings. A provider-specific
+status or error name may be retained as sanitized metadata, but MUST NOT replace
+these values or change fallback eligibility.
+
+| Failure | Category | Code |
+| --- | --- | --- |
+| Connection failure | `transient` | `connection_failed` |
+| Timeout before a partial stream | `transient` | `timeout` |
+| Rate limit | `transient` | `rate_limited` |
+| Provider server error | `transient` | `server_error` |
+| Service unavailable | `transient` | `service_unavailable` |
+| Provider overload | `transient` | `overloaded` |
+| Missing or rejected credential | `authentication` | `invalid_credential` |
+| Credential lacks access | `authorization` | `permission_denied` |
+| Billing account inactive or payment required | `billing` | `billing_unavailable` |
+| Invalid provider request | `invalid_request` | `invalid_request` |
+| Unsupported capability or option | `unsupported` | `unsupported_capability` |
+| Structured output violates its schema | `invalid_response` | `invalid_schema` |
+| Request exceeds the model context window | `context_length` | `context_length_exceeded` |
+| Invalid endpoint, header, model, or local request configuration | `configuration` | `invalid_configuration` |
+| Caller cancellation | `cancelled` | `cancelled` |
+
+If a failure cannot be mapped confidently, the adapter MUST return `unknown` /
+`unclassified_provider_error`, which is non-retryable, rather than guessing a
+retryable category. A timeout or other error after a partial stream retains its
+mapped category and code, but its per-error retry eligibility is `false` and the
+fallback rule above prohibits automatic replay.
+
+Provider error classes stay internal. Existing `ProviderError` is too broad to
+drive this policy and existing `ErrorTaxonomy` was designed for CLI provider
+switching, so neither is the future API retry contract without an explicit
+mapping and contract tests.
+
+## State export, import, and restart safety
+
+Plain Ruby state export is a versioned data document, not a serialized Ruby
+object. It contains normalized messages, stable message/tool-call IDs, completed
+tool results, pending tool calls and decisions, request IDs, and attempt reports.
+It never contains credentials, callbacks, open streams, tool implementations,
+authorization decisions, or mutable provider client objects.
+
+Import validates the version and structure and reconstructs the normalized
+conversation. The caller must re-supply tools, authorization, candidates,
+credentials, observers, retry limits, and cancellation. Unknown versions fail
+explicitly. Export/import round-trip tests must prove that completed tool IDs
+are not re-executed and unknown usage remains unknown.
+
+The restart guarantee is limited to checkpoints. A saved provider response or
+tool result is skipped after restoration. A process crash after an external
+tool side effect but before its result is durably saved can execute the tool
+again. No transcript format can close that window. Tools therefore need a
+caller-owned idempotency key derived from the stable tool-call ID, or explicit
+reconciliation before replay. Provider requests have the same ambiguity when a
+response is lost after the provider accepted it.
+
+## RubyLLM 2.0 mapping and alternatives
+
+The investigation used RubyLLM 2.0.0. RubyLLM remains an implementation detail;
+the harness public API MUST NOT expose its classes or private persistence
+records.
+
+| Contract area | RubyLLM 2.0 mapping | Decision or gap |
+| --- | --- | --- |
+| Chat/protocols | `RubyLLM.chat`, messages, tools, stream callbacks | Candidate adapter; normalize all values and errors |
+| Schema | `with_schema`, `response.parsed`, model capability registry | Candidate; distinguish enforced schema from JSON mode |
+| Embeddings | `RubyLLM.embed` and normalized vectors/usage | Candidate first capability; persistence remains in Paid |
+| Custom headers | `with_headers` | Candidate; contract-test merging and secret redaction |
+| Endpoint/credentials | provider configuration | Global mutable configuration is unsuitable; require request-local isolation or an upstream-supported client boundary |
+| Retries | Faraday retry middleware, default three retries | Disable with `max_retries: 0` so one call is one physical attempt; the harness sequences bounded retry and fallback itself; never nest |
+| Fallback | `with_fallbacks` and callbacks | Harness sequences candidates per call; `with_fallbacks` usable only if exact candidates, credentials, and per-advance observer control are preserved |
+| Cancellation | chat cancellation and `CancelledError` | Adapt to the common token and retain partial stream state |
+| Attempt usage | `usage.ruby_llm` per physical attempt | Useful facts, but the public payload has no stable attempt ID; harness must add one |
+| Plain Ruby resume | transcript can be reconstructed manually | No documented state export/import API; implement normalized export/import outside RubyLLM |
+| Rails resume | `acts_as_chat` transcript plus supporting records | Technically restart-safe at checkpoints; at-least-once side effects remain |
+
+### Optional Rails supporting tables
+
+RubyLLM 2.0 owns `ruby_llm_models`, `ruby_llm_tool_calls`,
+`ruby_llm_usages`, and `ruby_llm_batches`. Only the middle two are candidates
+for early chat adoption; batches are out of scope, while the model registry is
+needed only if capability/pricing lookup uses it.
+
+`ruby_llm_tool_calls.tool_call_id` is unique and can preserve the provider tool
+request/result link. It is acceptable only after tests prove that the harness's
+stable tool ID maps without collision and Paid tenant scoping is enforced
+through the owning application message/chat. The supporting table has no
+standalone tenant column, so every read/write path must join through a
+tenant-owned record and cross-tenant tests are mandatory.
+
+`ruby_llm_usages` records one physical attempt and links polymorphically to the
+application chat and optionally a message. It preserves failed/cancelled usage,
+but its row ID and record class are private and its public instrumentation has
+no stable attempt ID. Paid cannot use that row ID as the cross-system accounting
+key. The harness-generated `attempt_id` must be persisted alongside Paid's
+ledger, with an upstream-supported metadata column or mapping required before
+adopting this table as the authoritative delivery source.
+
+RubyLLM has no application-owned `Model`, `ToolCall`, `Usage`, or `Batch` model;
+its record classes are explicitly implementation details. Paid keeps its chat
+and message domain records, tenant ownership, message links, audit actor, and
+authorization. A Rails adoption requires generated-migration review, backup,
+production-snapshot rehearsal, backfill verification, rollback rehearsal, and
+historical/pending-conversation tests. Reverting the gem is not a data rollback.
+
+### Persistence alternatives
+
+1. **Retain Paid persistence and loop over normalized transport.** Lowest
+   migration risk and the current recommendation. Implement plain Ruby
+   export/import and stable IDs in the harness.
+2. **Use RubyLLM tool-call and usage tables selectively.** Potentially removes
+   bookkeeping, but only after stable-attempt mapping, tenant-scoped access,
+   audit, and migration tests are complete.
+3. **Delegate the full loop and all supporting tables.** Not recommended now.
+   It does not yet demonstrate reduced maintenance across both repositories and
+   increases migration and recovery coupling.
+
+The state investigation is therefore positive for checkpoint-based Rails
+restoration and normalized plain Ruby reconstruction, and negative for
+exactly-once recovery or an off-the-shelf plain Ruby export/import mechanism.
+
+## Current harness gaps and incremental delivery
+
+The current transports already normalize basic text, tool calls, token totals,
+and some HTTP errors. They do not provide request-local custom headers,
+per-request timeout/retry/cancellation, structured output, embeddings, stable
+attempt IDs, per-attempt usage, partial terminal results, state export/import,
+or explicit capability outcomes. `Conversation` stores in-memory history and
+provider formatters but has no serialization contract.
+
+Ship capabilities independently in this order:
+
+1. common values, capability discovery, classified errors, and attempt reports;
+2. embeddings for verified operation/provider/custom-endpoint scopes;
+3. normalized non-streaming and streaming chat transport;
+4. structured output for verified model/protocol combinations;
+5. plain Ruby state round trips; and
+6. optional Rails persistence evaluation, then loop evaluation.
+
+Each implementation issue starts with failing contract tests for request-local
+credential isolation, custom endpoints/headers, unsupported outcomes,
+classified errors, bounded non-nested retries, cancellation, partial streams,
+stable IDs, and unknown usage where applicable. Provider-specific fixtures and
+types stay behind the harness boundary.
+
+## Compatibility and release evidence
+
+AgentHarness currently supports Ruby 3.2 and later and must remain usable as a
+plain Ruby gem. RubyLLM 2.0.0 itself supports Ruby 3.1.3 and later, but adding it
+would introduce Faraday, event-stream parsing, Schematist, Marcel, and Zeitwerk
+runtime dependencies. A capability issue must measure and publish the resolved
+dependency set and test the harness minimum Ruby version before adoption.
+
+Rails and Active Record remain optional. Requiring `agent_harness` in a process
+without Rails MUST NOT load Active Record, connect to a database, or require
+supporting tables. Rails integration belongs behind an optional require and
+adapter.
+
+For every capability, release evidence must name:
+
+- the first published, installable agent-harness version containing it;
+- supported operation/provider/protocol/authentication combinations;
+- upstream contract and integration test runs on the minimum Ruby version;
+- verification of request-local secrets and absence of secret-bearing logs;
+- retry/cancellation and attempt-accounting test evidence;
+- the exact Paid and agent-image versions that consume the release; and
+- retained paths and follow-up issues for combinations not migrated.
+
+Paid issue `viamin/paid#4014` should receive this compatibility result, the
+state-restoration conclusion, the stable-ID gap, and the per-capability release
+evidence. Downstream adoption cannot proceed from this design issue closing or
+from a Git tag alone.

data/lib/agent_harness/providers/codex.rb

@@ -3,6 +3,7 @@
 require "json"
 require "net/http"
 require "uri"
+require_relative "codex_model_discovery"
 
 module AgentHarness
   module Providers
@@ -12,6 +13,7 @@ module AgentHarness
     class Codex < Base
       include RateLimitResetParsing
       include McpConfigFileSupport
+      include CodexModelDiscovery
 
       StreamingEvent = Struct.new(
         :type, :turn, :tokens, :error_message, :tool_name, :raw_event
@@ -546,6 +548,24 @@ module AgentHarness
           parser_instance.send(:classify_model_rejection, output, configured_model: configured_model)
         end
 
+        # Successful assistant/tool output can quote the exact rejection text.
+        # Only CLI stderr and explicit JSONL error envelopes are evidence.
+        def classify_model_rejection_from_result(stdout:, stderr:, configured_model: nil)
+          texts = stdout.to_s.each_line.filter_map do |line|
+            event = parse_stdout_jsonl_event(line.strip)
+            next unless event.is_a?(Hash)
+
+            event = unwrap_classification_event(event)
+            extract_jsonl_error_text(event) if event.is_a?(Hash)
+          end
+          texts << stderr.to_s
+          texts.each do |text|
+            rejection = classify_model_rejection(text, configured_model: configured_model)
+            return rejection if rejection
+          end
+          nil
+        end
+
         private
 
         def classify_stdout_chunk(text, buffer)
@@ -1095,11 +1115,15 @@ module AgentHarness
       end
 
       def fetch_model_list(rejected_model_id:, allowed_model_ids:, env:, timeout:)
-        result = @executor.execute_interactive(
-          [self.class.binary_name, "app-server", "--listen", "stdio://"],
-          timeout: timeout,
-          env: env
-        ) { |stdin, stdout| exchange_model_list_requests(stdin, stdout) }
+        result = if @executor.respond_to?(:execute_interactive)
+          @executor.execute_interactive(
+            [self.class.binary_name, "app-server", "--listen", "stdio://"],
+            timeout: timeout,
+            env: env
+          ) { |stdin, stdout| exchange_model_list_requests(stdin, stdout) }
+        else
+          execute_model_discovery(env: env, timeout: timeout)
+        end
         return unavailable_model_discovery(:app_server_failed, stderr: result.stderr) unless result.success?
 
         response = parse_app_server_response(result.stdout, 2)

data/lib/agent_harness/providers/codex_model_discovery.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  module Providers
+    # Runs the interactive protocol beside the CLI, including for executors that
+    # only expose execute (Docker/remote transports). Codex's npm installation
+    # already requires Node. No shell, host credentials, or host CLI is used.
+    module CodexModelDiscovery
+      SCRIPT = <<~'JS'
+        const { spawn } = require('node:child_process');
+        const child = spawn(process.argv[1], ['app-server', '--listen', 'stdio://'], {stdio: ['pipe', 'pipe', 'pipe']});
+        let buffer = '', bytes = 0, page = 0, done = false;
+        const models = [], cursors = new Set();
+        const send = value => child.stdin.write(JSON.stringify(value) + '\n');
+        const finish = (code, value) => {
+          if (done) return;
+          done = true;
+          clearTimeout(timer);
+          if (value) process.stdout.write(JSON.stringify(value) + '\n');
+          process.exitCode = code;
+          child.stdin.end();
+          child.kill('SIGTERM');
+          setTimeout(() => child.kill('SIGKILL'), 250).unref();
+        };
+        const timer = setTimeout(() => finish(1), Number(process.argv[2]));
+        child.on('error', () => finish(1));
+        child.stdin.on('error', () => finish(1));
+        child.stderr.on('data', () => {});
+        child.on('close', () => { if (!done) finish(1); });
+        child.stdout.on('data', chunk => {
+          bytes += chunk.length;
+          if (bytes > 1048576) return finish(1);
+          buffer += chunk.toString();
+          let end;
+          while (!done && (end = buffer.indexOf('\n')) >= 0) {
+            const line = buffer.slice(0, end); buffer = buffer.slice(end + 1);
+            let msg; try { msg = JSON.parse(line); } catch { continue; }
+            if (msg.id !== 1 && msg.id !== 2) continue;
+            if (msg.error) return finish(0, {id: 2, error: msg.error});
+            if (msg.id === 1) {
+              send({method: 'initialized', params: {}});
+              send({id: 2, method: 'model/list', params: {limit: 100}});
+            } else {
+              if (!Array.isArray(msg.result?.data)) return finish(1);
+              models.push(...msg.result.data);
+              const cursor = msg.result.nextCursor;
+              if (!cursor) return finish(0, {id: 2, result: {data: models}});
+              if (++page >= 10 || cursors.has(cursor)) return finish(1);
+              cursors.add(cursor);
+              send({id: 2, method: 'model/list', params: {limit: 100, cursor}});
+            }
+          }
+        });
+        send({id: 1, method: 'initialize', params: {clientInfo: {name: 'agent-harness', version: '1.0.0'}}});
+      JS
+
+      # Fresh account-local discovery. The caller owns selection policy and must
+      # still smoke-test its selected model; model/list is not execution proof.
+      def discover_available_models(env:, timeout: 15)
+        result = execute_model_discovery(env: env, timeout: timeout)
+        return unavailable_model_discovery(:app_server_failed) unless result.success?
+
+        response = parse_app_server_response(result.stdout, 2)
+        return unavailable_model_discovery(:model_list_missing_response) unless response
+        return unavailable_model_discovery(:model_list_error) if response["error"]
+
+        entries = Array(response.dig("result", "data")).filter_map { |entry| normalize_model_entry(entry) }
+          .reject { |entry| entry[:hidden] }.uniq { |entry| entry[:id] }
+        return unavailable_model_discovery(:no_compatible_model) if entries.empty?
+
+        preferred = entries.find { |entry| entry[:is_default] } || entries.first
+        self.class::ModelDiscovery.new(status: :available, models: entries,
+          recommended_model_id: preferred[:id], source: :codex_app_server_model_list)
+      rescue TimeoutError
+        unavailable_model_discovery(:app_server_timeout)
+      end
+
+      private
+
+      def execute_model_discovery(env:, timeout:)
+        @executor.execute(
+          ["node", "-e", SCRIPT, self.class.binary_name, [(timeout * 1000).to_i - 500, 100].max.to_s],
+          env: env, timeout: timeout
+        )
+      end
+    end
+  end
+end

data/lib/agent_harness/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentHarness
-  VERSION = "0.37.5"
+  VERSION = "0.39.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-harness
 version: !ruby/object:Gem::Version
-  version: 0.37.5
+  version: 0.39.0
 platform: ruby
 authors:
 - Bart Agapinan
@@ -97,6 +97,7 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/provider-neutral-api-execution-contract.md
 - json-2.18.1.gem
 - lib/agent-harness.rb
 - lib/agent_harness.rb
@@ -128,6 +129,7 @@ files:
 - lib/agent_harness/providers/anthropic.rb
 - lib/agent_harness/providers/base.rb
 - lib/agent_harness/providers/codex.rb
+- lib/agent_harness/providers/codex_model_discovery.rb
 - lib/agent_harness/providers/cursor.rb
 - lib/agent_harness/providers/gemini.rb
 - lib/agent_harness/providers/github_copilot.rb