@opsregistry/adapter-openai-compatible

Provider-neutral stateless Responses API transport and authenticated MCP function loop for OpsRegistry it.aiResponse.create. No Polza, Yandex, Timeweb or ERP dependency.

Configure a trusted HTTPS baseUrl, inference API key, model, instructions, MCP URL/per-user headers, limits and awaited beforeRequest budget reservation. Optional extraBody supplies provider options; reserved fields (tools, model, output limits, streaming) cannot be overridden. Optional readCostRub normalizes billed usage. Providers without that field require their own accounting policy.

Each outcome contains result, opaque server-only state and costRub. Persist state under the same principal and permissions; never accept it from a browser/model. Endpoint/model changes invalidate continuations. The consumer MUST atomically claim a continuation once and never retry uncertain writes. This library has no database and is not an idempotency store.

Fresh MCP annotations classify reads. Unknown/write tools stop before execution and yield exact pending approvals (name, arguments, call ID, metadata fingerprint). Approval is external to the model and valid only for that action. Denial executes nothing. The loop has explicit tool/output/ context bounds, a 100-second deadline and no retries. MCP headers never enter model requests.

Agent handoff

bun test, bun run check, bun run build. Tests cover read/history, write approval and denial, changed policy, budget rejection before writes, no retries, provider isolation and reserved options. Consumer owns authorization, persistence, atomic replay protection and monetary ledger. Next: optional Chat Completions dialect, streaming, cancellation and history compaction. Do not infer support for remote MCP/history/cost from an SDK compatibility claim. Pin provider capabilities explicitly. Yandex currently retains its separate native remote-MCP implementation; Polza is a thin provider wrapper over this package. Timeweb integration is not yet implemented.

Invoice recognition (0.4.0)

prepareDocument(bytes) prepares PDF/JPEG/PNG (10 MiB, 5 pages) using Sharp and Poppler (pdfinfo, pdftotext, pdfimages, pdftoppm; Ubuntu: poppler-utils). Temporary originals/renders are deleted in finally; image metadata is stripped. recognizeInvoice(config, pages) implements documents.invoice.recognize with one stateless strict JSON Responses request and no tools. beforeRequest must reserve the consumer's budget before inference. Unknown image token accounting fails closed. Amounts remain decimal strings, unknown fields null; arithmetic conflicts become warnings. It never selects ERP identities, creates records or retries inference.

Agent follow-up: add provider-verified image accounting for further models; extraction for other document types must have separate contracts. Do not weaken limits or turn untrusted document text into instructions. Consumers own original storage, permissions, deduplication, approval and unknown-cost reconciliation. Tests use fake provider responses and real local Poppler, without paid requests.

Incremental budget reservations (0.5.0)

Opt-in incrementalBudget: true invokes beforeRequest before each paid model request, with cumulative: true: observed token usage so far plus the next request's conservative byte/output bound. Consumers must atomically extend the same execution's reservation, charging only its increase against daily limits and never shrinking it. Approved mutations reserve their bounded follow-up response before execution. Do not reuse or reopen settled/uncertain reservations. A refusal stops execution; unknown outcomes remain reserved and must not be retried. Legacy whole-loop reservation remains the default. The tool-call ceiling (at most eight) and all approval controls remain.

Consumer preflight (0.6.0)

Optional validateToolCall(name, args) must be side-effect-free. A returned error is fed back to the model as a failed, unexecuted call before any approval is offered; the correction consumes the existing step budget. Returning null allows the usual read/write policy to proceed. Approved actions are revalidated before reservation or execution; a changed/invalid contract blocks the write. Validation never replaces user authorization or exact approval. No ERP schemas are embedded in this runtime. Approval continuations retain the original bounded loop context ceiling (0.5.1), instead of incorrectly applying the smaller initial-message limit to tool history.

Document coverage (0.7.0)

recognizeTradeDocument implements documents.tradeDocument.recognize: invoice, УПД and goods waybill projections with separate parties, tax bases and extraction issues. Existing recognizeInvoice retains its invoice-only contract. No tools, provider storage, auto-retries or database writes during recognition. Output truncation or invalid JSON is a failure, never a usable partial accounting document. Consumers own document storage, explicit recognition upgrades, budget and accounting approval. summarizeConversation is a bounded, tool-free text operation; consumers must retain exact action receipts separately. No automatic summarization is enabled by this package.

Tool budget context (0.7.1)

Each model request receives the remaining tool-call count, including discovery and schema calls. Exhaustion disables tools and explicitly asks for the actual step-limit reason and completed/pending work, not an invented authorization error. The instruction is included in context and reservation bounds. No extra calls, automatic retries or approval bypasses are introduced; business workflow prioritization stays with consumers.