Module formal_ai_client 

Minimal client of the OpenAI-compatible agent-mode endpoint of Formal AI (POST /api/openai/v1/chat/completions), used by --use-formal-ai (issue #255). Mirrors js/src/lib/formal-ai-client.js. It offers the bash tool and the structured read tool, plus edit and write when workspace changes are allowed (issue #258): Formal AI picks the call, start decides whether and how it runs.

An HTTP error keeps a bounded, sanitized excerpt of its body (the error type, message and a preview) and the attempt count, so a failing runtime names its cause (issue #257).

The runtime is always a loopback http:// server, so a small blocking HTTP/1.1 client over std::net is enough; it polls for cancellation and the time budget while it waits.

Structs

ClientError

A failed exchange with Formal AI and the exit status it maps to.

Completion

One chat completion, normalized for the task loop.

HttpClient

Client bound to one runtime over HTTP.

ToolCall

One tool call Formal AI asked for.

Enums

HttpError

Why an HTTP exchange failed.

Constants

API_PREFIX

BASH_NAMES

Names Formal AI may use for the bash tool.

GAP_SCHEMAS

Known structured gaps Formal AI answers instead of claiming success.

TOOL_NAMES

Every tool name start accepts.

Traits

CompletionClient

Something that answers chat completions (HTTP, or a replay in tests).

Functions

bash_tool

The bash tool offered to Formal AI.

http_error_details

Structured diagnostics of an HTTP error response: httpStatus, errorType, errorMessage, bodyPreview and bodyChars (same keys as JavaScript).

http_error_message

Formal AI returned HTTP <status>: [<type>: ]<message or preview>.

http_request

One blocking HTTP/1.1 exchange with Connection: close.

offered_tools

Tools offered to Formal AI: the change tools only when the effect mode allows changes, so the advertised contract matches the policy.

parse_completion

Normalize one chat completion into what the loop needs.

parse_http_url

Host, port and path prefix of an http://host:port/prefix URL.

recognize_capability_gap

Recognize a final answer that is exactly a known Formal AI capability gap: {schema, target, reason, missingCapabilities, complete, verified}. Only the runtime’s own answer counts: text that a tool result in this run contained (file data echoed back) is never taken as a gap.

sanitize_diagnostic

One line of untrusted diagnostic text, bounded and without credentials: known secrets, authorization headers, bearer or basic credentials and credential-named fields are masked, and control characters become spaces.