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§

AllowAll
The default approver: allows everything, instantly — headless consumers (locode-exec, evals) are byte-for-byte unchanged in behavior.
AnthropicProvider
The live Anthropic Messages Provider (non-streaming).
ApprovalRequest
The pre-dispatch view of one tool call — what the studied UIs render their permission prompts from (request args, not host-resolved detail).
BuiltProvider
A constructed provider plus the model name it resolved (for the report envelope and engine config).
CancellationToken
A token which can be used to signal a cancellation request to one or more tasks.
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).
DiscoveredSkills
What discovery produced.
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.
GitMeta
Git provenance for the header (grok summary.json’s git fields).
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.
InstructionEntry
One discovered instruction file: where it came from, and its contents.
InstructionsConfig
How project-instruction discovery behaves. All fields have defaults; a caller (the CLI today, a settings layer later) overrides them.
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.
ProjectInstructions
Discovered project instructions: ordered entries, lowest-precedence first, so a later (deeper) entry wins on conflict. Neutral — the engine owns rendering/injection.
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).
RolloutContents
A parsed rollout: the header plus the replayable message history.
SamplingArgs
Provider-neutral sampling knobs — the common core only.
Session
One driven agent session. Owns the conversation history across runs: a second Session::run on the same session continues the same conversation (ADR-0016) — the exact call shape an interactive frontend needs for follow-up turns.
Settings
The typed view of the merged settings (v1 fields, ADR-0024 §1.4). Unknown keys are tolerated at every layer; absent keys are None/empty.
SettingsLoad
The loader result: the merged settings plus human-readable warnings the caller surfaces on stderr (this crate never prints).
Skill
One discovered skill.
SkillsConfig
Inputs for discover — all of it derived from resolved settings, which is what makes the load order an invariant (ADR-0025 §6.1).
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.
TraceExtras
Construction-time inputs the Event::Init event doesn’t carry.
TraceWriter
The rollout writer: feed it every engine Event; it materializes the file on Init (header + preamble message lines) and appends one message line per appended Message. All other event types are ignored — deltas are display-only and the report already has its own artifact (ADR-0014).
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.
Decision
The approval vocabulary — deliberately minimal (ADR-0017 Option V1): stickiness and richer choices live in approver implementations.
DeveloperRendering
How Role::Developer messages are rendered on the wire (plan §4.1).
Effort
One rung of the locode effort ladder.
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).
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).
SkillScope
Where a skill came from — and, on a collision, how it is addressed.
SkillsExtraEntry
One validated skills.extra entry (ADR-0024 §1.4).
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§

Approver
Decides whether one tool call may run. Consulted by the engine per call, serially, before dispatch; the await suspends only this call.
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.
decode_cwd_dirname
Decode a session-directory name back to the cwd it encodes, or None for a hash-fallback name (recover via the .cwd sidecar) or a malformed escape.
discover_skills
Discover every skill visible from cwd.
encode_cwd_dirname
Encode a (canonicalized, absolute) cwd into its session-directory name.
find_latest_rollout
The newest resumable rollout for cwd (--continue): list the one encoded directory, take rollouts newest-first by filename (the timestamp prefix sorts chronologically), and return the first whose header parses with kind == "main" — unknown kinds are not listed (§2.4 rule 3), but remain reachable by id.
find_rollout_by_id
Locate a rollout by session id (--resume <id>): the cwd’s directory first, then every other session directory (Claude’s scoped-then-global resolver). Any kind is resumable by id.
load_project_instructions
Discover project instructions for cwd under cfg.
load_settings
Load and merge the five layers for cwd. flag is the raw --settings value (a path, or inline JSON when it starts with {).
locode_home
The resolved home, memoized for the process (env is read once).
read_rollout
Read a rollout tolerantly (ADR-0024 §2.4 rules 1-2): unknown record types and unknown payload fields are skipped/ignored; an unparsable line (the torn tail) is skipped; a compacted record replaces all prior messages with its replacement_history.
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.
update_user_setting
Write key = value into the user settings file, preserving every other key.

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.