Skip to main content

Crate locode_core

Crate locode_core 

Source
Expand description

locode — the facade crate: the public surface for consumers (the future locode-app, and locode-exec as the reference consumer).

Two curated surfaces (Task 14, SPEC Users #3/#4):

Downstream code should depend on this crate, not the locode-* internals — the internals may churn; this surface is the stable contract.

Modules§

grok
The grok pack — a faithful port of Grok Build’s xai-grok-tools toolset, trimmed to headless-minimal (ADR-0012), over locode-host. Task 13 renders its real system prompt; all five grok tools are wired here.

Structs§

AnthropicProvider
The live Anthropic Messages Provider (non-streaming).
BuiltProvider
A constructed provider plus the model name it resolved (for the report envelope and engine config).
Completion
One normalized completion: the parsed result of a single model call (ADR-0007).
Conversation
A full conversation: one uniform stream of role-tagged messages (ADR-0013).
ConversationRequest
One provider-neutral sampling request (ADR-0007).
Dispatched
The outcome of one Registry::dispatch: both the history and report views, plus a fatal signal.
EngineConfig
Everything the loop needs that isn’t the provider, registry, preamble, or sink.
ExecLimits
Limits on shell execution. Defaults mirror Grok Build (the primary model).
FnSink
Forwards each event to a closure — e.g. a JSONL stdout writer for stream-json, or a Vec-pushing closure in tests.
GrokPack
The grok harness pack (a zero-sized &'static singleton).
Host
The injectable side-effect seam (ADR-0008). Construct once per session, share behind an Arc; holds the jail root + policy and the exec/truncation limits.
HostConfig
Construction-time configuration for a Host.
Message
One message: a role plus an ordered list of content blocks.
MockProvider
A provider that replays a fixed script of results, one per complete() call.
ModelConfig
The per-model wire configuration record (ADR-0007 + plan §3.1/§9).
NullSink
Drops every event — for the json/text output modes that only want the report.
OpenAiModelConfig
The per-model config record for the OpenAI wire family (plan §3.2 + §A.5).
OpenAiResponsesProvider
The live OpenAI Responses Provider (non-streaming, stateless).
PackContext
Dynamic, per-run context a pack’s preamble is rendered against.
ProviderBuildError
A provider construction failure (missing env, bad config, unknown name): pre-run by nature — surfaced before any session starts.
ProviderInit
Per-run inputs a factory may use when constructing its provider.
ProviderRegistry
The --api-schema name space: ordered name → factory entries.
Registry
A set of tools keyed by their model-facing wire names, plus the one dispatch door every call funnels through (ADR-0008).
Report
The single JSON document locode-exec prints to stdout (ADR-0009).
RetryPolicy
Transport-retry knobs (Task-12 plan §3.6; sources: Claude Code 500ms·2ⁿ cap 32s, grok’s 429-cap-2 and 120s Retry-After cap, codex’s ±10% jitter).
SamplingArgs
Provider-neutral sampling knobs — the common core only.
Session
One driven agent session. Owns the conversation history for the run (ephemeral).
ToolCallRecord
A report-side record of one tool call (distinct from the in-conversation ContentBlock::ToolUse): the structured output view, not the model-facing text.
ToolCtx
The context handed to a tool for one call.
ToolSpec
A provider-neutral tool spec: name + description + args JSON Schema.
UnknownHarness
An unknown --harness selector — a caller/config error (soft, never a panic).
Usage
Token accounting parsed from the provider’s terminal usage event.

Enums§

ApiBackend
Which endpoint family the wire talks to — selects auth header + quirks.
AuthScheme
The resolved credential and how to present it.
CacheHint
Where the wire should place prompt-cache breakpoints (ADR-0007).
ContentBlock
A typed piece of message content, modeled on Anthropic’s content blocks.
DeveloperRendering
How Role::Developer messages are rendered on the wire (plan §4.1).
Event
One event in the stream-json trajectory (one JSON object per line).
GrammarSyntax
The grammar language of a ToolInputFormat::Freeform tool.
ImageSource
The source of an image block.
OpenAiBackend
Endpoint family — quirks only; auth is always Bearer here.
PathPolicy
Whether the filesystem tools are jailed to the workspace root (ADR-0008 amendment).
ProviderError
Why a model call failed (ADR-0007).
ReasoningEffort
A neutral reasoning-effort level, mapped per-wire (ADR-0007).
ReasoningEncoding
How reasoning_effort is encoded on the wire (plan §4.4).
ReasoningFormat
The encoding/replay contract of a ContentBlock::Reasoning block.
ResultChunk
A single chunk of a tool result (a restricted set of block kinds).
Role
The author of a message (ADR-0013).
Status
The terminal state of a run. Serializes to the exact strings in ADR-0009.
StopReason
Why the model stopped generating (Anthropic-shaped, provider-neutral).
SystemPlacement
Where the hoisted System prompt is placed on the Responses wire.
ToolError
How a tool call failed, split into exactly two recovery paths (ADR-0004).
ToolInputFormat
How a tool’s input is specified: a JSON-schema function tool, or a freeform tool whose raw-text input is constrained by a server-side grammar (OpenAI Responses custom tools — codex’s apply_patch). Exactly one of the two — an enum, not optional fields, so invalid states are unrepresentable.
ToolKind
A canonical classification tag for a tool, used only to align comparable tools across harness packs for A/B analysis (ADR-0003) — it is not the wire name (that is assigned per-pack at registration) and not the Rust type name.

Constants§

MODEL_OUTPUT_BUDGET
Default model-facing byte budget. Matches Grok’s shell output cap.

Traits§

AuthRefresh
Re-resolve the credential after a 401/403 (plan §4.5).
DynTool
The object-safe, type-erased tool the registry stores.
EventSink
A sink for the loop’s Events. &mut self so a writer sink can buffer/flush; object-safe so locode-exec can pick one at runtime by --output-format.
Pack
A faithful reproduction of one harness: its real toolset + its base prompt, selected whole via --harness (ADR-0012). One pack is active per run.
Provider
A model-sampling wire: builds a request, calls the model, normalizes the response.
Tool
A tool authored against concrete types; the wire schema is derived from Tool::Args, never hand-written (ADR-0003).
ToolOutput
The model-facing rendering of a tool’s output.

Functions§

available
The registered --harness names, in stable order.
reconstruct_conversation
Reconstruct the full Conversation from a stream-json event trajectory.
resolve
Resolve a --harness <name> to its pack.
truncate_for_model
Bound text to roughly budget bytes for model consumption, keeping the head and tail and eliding the middle (middle-truncation, Codex-style) with a byte-count marker in the seam.

Type Aliases§

ProviderFactory
A named provider constructor: env/config resolution belongs inside the factory so selection stays lazy — only the chosen wire pays its setup.