Crate supercode_runtime 

Optional native model and tool runtime for Supercode.

This package owns provider request/event/usage contracts, the OpenAI-compatible streaming transport, cache planning, request budgeting, and bounded background state. The complete Agent and tool composition lives in supercode-harness; foreign session codecs live in supercode-interchange; reversible reduction is optional.

Modules

background

P5-6 (COMPOSABLE-HARNESS-DESIGN.md §2 module 4 tools.background: “D1 background exec + monitor/event feed; D10 bg-manager; D3 self-paced/ scheduled loops”; §2.1 “tools.background → permissions.approvals (auto-policy) [C6 as dep]”; §2.2 C6): the pure, agent-independent data shapes and bounded-buffer arithmetic a runtime agent’s background_exec/background_status/background_list/background_kill intrinsics build on — kept separate from agent.rs so the bounded- capture truncation logic and job-id shape are unit-testable without a full Agent/mock-Provider/real-subprocess harness, the same “pure config → set, testable without the loop” precedent subagent runtime documents for itself (P5-3).

Structs

ChatRequest

A single model-completion request.

OpenAiProvider

An OpenAI-compatible HTTP provider. The composition layer supplies its endpoint, credentials, and headers from runtime configuration.

PromptTokensDetails

The cache portion of Usage::prompt_tokens_details.

ToolSchema

A tool advertised to a model.

Usage

Token accounting returned with a completion.

Enums

AgentEvent

Streaming events emitted by a native runtime agent as a turn unfolds.

CachePlan

Prompt-caching plan applied while building a provider request.

RuntimeError

A provider-transport or response error.

Constants

CONTEXT_RESPONSE_RESERVE_TOKENS

PARITY-18 — headroom reserved for the model’s own completion, folded into the context-guard boundary alongside with_guard_margin. Neither estimate_view_tokens nor estimate_request_tokens counts anything for the reply the model is about to generate — this is a flat token budget carved out of the model’s context window for it, since the completion shares the same window as the request on every provider this crate targets.

UNKNOWN_MODEL_CONTEXT_FLOOR

Conservative fallback context limit for an unrecognized model.

Traits

Provider

The transport abstraction. Implement this to back the agent with something other than an OpenAI-compatible HTTP endpoint (a local model, a mock, etc.).

Functions

context_guard

PARITY-18 D1/D2/D4 — the single context-guard decision, shared by every call site that must decide whether a request is safe to send: the CLI’s resume_cmd preflight check AND Agent::run_loop’s per-send check (D4 — the guard is a session invariant, not a one-shot preflight, so turn 2+ and /expand all are covered too). Because both call through this one function, a request can never pass one gate and fail the other — there is only one formula.

estimate_deferred_schema_tokens

Schema-token estimate for the B6 “tools” banner line: the estimate over the serialized full ToolSchema list minus the estimate over the serialized advertised list — i.e. the token cost of what’s currently deferred (hidden behind tool_search) rather than eagerly advertised. Saturates to 0 rather than underflow if advertised somehow estimates larger than full (e.g. formatting differences), since “negative deferred tokens” has no meaning for the banner.

estimate_request_tokens

PARITY-18 D1 — the full wire-request token estimate: every message in messages (including the system prompt at index 0) plus the serialized tools schema array, which is a real part of the provider request but — before PARITY-18’s re-fix — was never counted by the preflight guard at all. A session whose messages alone fit comfortably could still carry a fat builtin/MCP tool-schema array that blows the real wire request; this is the fix.

estimate_tokens

Deterministic token estimate: ceil(utf8_bytes / 4).

estimate_view_tokens

Estimate the serialized wire size of canonical messages.

fmt_approx_tokens

Render an estimated token count in the shared UX style: ~21,904 tok (tilde prefix + comma-grouped thousands, matching the stub-line comma style in reduce.rs). Every figure that flows through estimate_tokens/estimate_view_tokens/estimate_deferred_schema_tokens should be rendered through this helper so the ~ discipline (D11) is applied uniformly rather than ad hoc at each call site.

glob_match

Match a tool or path name against a minimal * wildcard pattern.

model_context_limit

Look up a model’s context-window size by its full provider slug.

with_guard_margin

Apply the runtime’s 5/4 context-guard safety margin to a raw token estimate. Rounds up (div_ceil), never down — the margin only ever pushes the boundary check to be more cautious.

Type Aliases

EventSink

A sink for AgentEvents.

Result

Result type for native runtime operations.