Crate warble_claude_code

Expand description

Warble back-end for the Claude Code CLI target.

Consumes a compiled Warble IR (JSON) and emits a Claude Code agent runtime (agent files under .claude/agents/, settings, and RUN.md) — the static-file target, which needs no SDK, so it lives natively in Rust alongside the compiler and is driven by the warble CLI. Also hosts the deterministic reference renderer (render) and the capability-manifest projection (manifest).

Dispatch is keyed on IR enums (realization_kind, trigger.kind, effect.outcome.kind), never on a component’s id/verb. Enum arms not yet realized fail loudly (a “wall-hit”).

This crate is not a standalone tool — you install warble-cli (the warble binary), which links this crate in directly, and warble dispatch --target claude-code (or claude-code:headless / claude-code:interactive, the default) selects it at dispatch time.

Modules§

conditional: Deterministic realization of a conditional step’s closed-vocabulary when guard — mirrors dispatcher/claude-agent-sdk/src/conditional.ts field-for-field (see that module’s doc for the full R1 repair-fold-into-loop / R2 guarded-skip design).
ir: Typed view of the Warble IR (warble_ir_version: 0.7) that this back-end consumes.
slots: Slot resolution — turning IR 0.7’s declared slots into the text a model actually receives.

Structs§

CapabilityManifest
ContextInjection: Normalized, runtime-neutral context payload supplied to the dispatcher by its host.
ContextInjectionReport: Public report identity written beside every dispatched agent and copied into eval reports. It intentionally contains fingerprints/counts rather than private knowledge text.
DispatchError: A dispatch/render/resolve failure with a human-facing message. Every unsupported IR arm and every failed capability resolution surfaces as one of these (loud-fail) rather than emitting a silently-wrong agent.
Envelope: A parsed Warble render envelope (blocks + optional summary + optional verify facet).
ModelConfig: An ordered tier→binding map. Declaration order is priority: earlier tiers are “stronger” — used to pick the single model when a multi-tier component collapses to one agent. Alongside the authoring tiers (strong/cheap/custom, which components declare on steps) it carries the reserved ORCHESTRATOR_TIER used by the split driver.
NativeBinding
NativeMcpDescriptor: Exact server-derived connection material for the allowlisted native-session MCP server.
NativeSessionScope: A server-derived launch scope. This is deliberately a small producer input rather than session state: GenBI creates and authorizes it, Warble verifies its shape/canonical cwd and carries its opaque binding identity into the launch artifact, and the future runtime owns comparing it to its live binding generation/revision before spawning.
ProviderFragment: A single provider fragment: a partial target definition. Field names are snake_case to match the fragment YAML verbatim.
RenderOptions: Document rendering options.
ResolvedCapability
TierBinding: A tier’s full runtime binding: which provider serves it, at what endpoint (for OpenAI-compatible providers), running which model. The shorthand YAML form tier: <model> is a { provider: anthropic, endpoint: none, model: <model> } binding — so existing configs are unchanged, and the file target (which only reads model) behaves exactly as before.

Enums§

ContextInjectionMode: Which normalized semantic context is embedded into emitted agent prompts.
HybridRealization: How the file target realizes a hybrid binding’s LOCAL step (llm:per_step_provider, see capability-model.md §7.2): BashScript emits a Bash-run local-inference script (needs bash in the allowlist); McpServer emits a .mcp.json registering warble mcp-serve so the driver calls a local_infer MCP tool (a separate permission gate — no bash widening). Default BashScript.
NativePurpose: The only product purposes that may opt into the native Sessions launch contract.
RenderFlavor: Render flavor (ir-schema.md §v0.3 §4). programmatic (default): the agent stays read-only and emits a {blocks} envelope; a downstream renderer produces HTML deterministically. prompt: the plain-file fallback — the agent is granted scoped write and writes dashboard.html itself.
TargetId: The two claude-code targets: engine × mode.

Constants§

ANTHROPIC_PROVIDER: Well-known provider name: rides the Claude runtime (the default when provider: is absent).
BINDING_SPEC_VERSION: The binding spec version this module implements — see binding-spec.md, the authoritative, versioned source both back-ends conform to (kept in lockstep to avoid the IR’s own version-drift history).
DEFAULT_CONTEXT_INJECTION
DEFAULT_RENDER_FLAVOR
DEFAULT_TARGET: claude-code target’s default mode when the caller doesn’t specify one.
OPENAI_COMPAT_PROVIDER: Well-known provider name: an OpenAI-compatible endpoint (e.g. ollama’s /v1); requires endpoint.

Functions§

build_manifest: Project a resolved IR into its runtime-agnostic capability manifest.
compose_for_conformance: Compose against an empty tool map and report only the capability keys — the shape the shared conformance fixture asserts. Exposed for that suite rather than for the emit path, which needs the whole composed target and reaches compose_target directly.
emit_claude_code
emit_claude_code_with_context: As emit_claude_code_with_realization, with an explicit host-normalized context payload. This is the CLI host seam for --context-injection; the dispatcher performs no project I/O.
emit_claude_code_with_models: Emit Claude Code agent runtime files for a resolved IR into out_dir. Errors on any unsupported enum value rather than emitting a silently-wrong file. Runs the capability resolution pass first; on abort it errors and writes nothing. models resolves each step’s tier to a concrete model. A hybrid binding uses the default HybridRealization::BashScript; call emit_claude_code_with_realization to choose.
emit_claude_code_with_native_purpose: As emit_claude_code_with_providers, opting into the v2 native Sessions contract. purpose is a closed, server-selected allowlist; it selects neither a caller cwd nor prompt.
emit_claude_code_with_providers: As emit_claude_code_with_context, composing the base target with caller-supplied provider fragments. This is how a domain capability — one naming an external service rather than the runtime’s own structure — reaches this back-end without being hardcoded in it.
emit_claude_code_with_realization: As emit_claude_code_with_models, choosing how a hybrid binding’s LOCAL step is realized on the file target (bash-script script vs an MCP server). Only affects the hybrid path.
emit_codex_interactive
is_known_target
known_target_names
parse_envelope: Extract a Warble render envelope from raw agent output. The agent is asked to emit only the JSON envelope, but models routinely wrap it in ```json fences or surround it with a sentence. This is deliberately forgiving:
parse_provider_fragments: Parse one fragment file’s contents. Pure — file I/O stays in the CLI.
render_envelope_to_html: Render a full envelope to a single self-contained HTML document. Pure and deterministic: no clock, no randomness, stable ordering — the same envelope always produces identical bytes.
resolve_capabilities: Resolve every capability required by node against profile. Returns the report on success; errors (loud-fail) naming the capability + target if any required capability resolves to fail.
resolve_node_capabilities: Resolve one node’s required capabilities against target_id, erroring on any fail outcome (no silent degradation). Callers must not emit files when this errors.
setup_recovery_input_schema: The public, transport-independent input schema for the genbi_session report_setup_recovery MCP tool. The host validates monotonicity against its last accepted report; the schema deliberately carries neither identity nor any diagnostic text.
setup_recovery_instructions: The generated Setup-agent instruction for the v3 genbi_session discovery contract. This is deliberately prose plus closed examples rather than a second tool configuration.
validate_setup_recovery_report: Validate the producer-owned closed vocabulary without accepting or echoing a raw report. Hosts additionally own per-session authorization and monotonic sequence fencing.

Type Aliases§

Provider: Which provider serves a tier’s model — an open string, opaque to warble (mirrors how the IR treats tier; see binding-spec.md). Two well-known values get behavior baked into TierBinding parsing below (ANTHROPIC_PROVIDER, the default; OPENAI_COMPAT_PROVIDER, which requires endpoint), but warble does not validate this field against a fixed provider list — any other string is a valid, warble-unrecognized provider that passes through unchanged. Rejecting a genuinely unsupported provider is the consuming harness/back-end’s job (its per-provider adapter registry), never warble’s — warble stays opaque pass-through.
ResolutionReport