Module components

Expand description

Context-Generic Programming (CGP) substrate for VT Code

Applies the provider-trait pattern from CGP to decouple tool runtime composition from coherence restrictions. Instead of relying on blanket impls or adapter newtypes, each capability (approval, sandboxing, execution, metadata, etc.) is expressed as a provider trait with an explicit Context parameter. A lightweight wiring step maps named components to concrete providers per context type.

§Key ideas (from the RustLab 2025 CGP talk)

Provider traits move Self to an explicit generic parameter, bypassing Rust’s coherence/orphan restrictions.
Component names are zero-sized marker types that act as keys in a type-level lookup table.
delegate_components! wires component names to provider types for a given context, producing HasComponent implementations.
Consumer code depends only on the component name, not the concrete provider, enabling the same tool/request to run under different policies by simply switching the context.

§Dictionary-passing interpretation

This module intentionally mirrors dictionary-passing style for Rust traits. HasComponent<Name>::Provider is the elaborated “dictionary” selected for a capability, while the blanket consumer impls (CanApproveTool, CanExecuteTool, etc.) are the point where the compiler proves that the selected provider implements the required provider trait for the current context. That keeps the capability wiring explicit and avoids depending on deeper associated-type reasoning at call sites.

§Example

use vtcode_core::components::*;

// Define a context for interactive sessions
struct InteractiveCtx { /* ... */ }

// Wire components to providers
delegate_components!(InteractiveCtx {
    ApprovalComponent  => PromptApproval,
    SandboxComponent   => WorkspaceSandbox,
    ExecuteComponent   => DefaultExecutor,
});

// Define a CI context with different providers
struct CiCtx { /* ... */ }

delegate_components!(CiCtx {
    ApprovalComponent  => AutoApproval,
    SandboxComponent   => StrictSandbox,
    ExecuteComponent   => DefaultExecutor,
});

Structs§

AutoApproval: Always-approve provider for CI/test contexts.
BenchCtx: Benchmark runtime context — auto-approves, no sandbox, no static middleware.
CachedResults: Cache provider backed by UnifiedCache.
CiCtx: CI/automation runtime context — auto-approves, strict sandbox.
ComposableRuntime: A generic tool runtime that composes approval + sandbox + execution through CGP component wiring.
DefaultMetadata: Default metadata provider for contexts that do not customize tool metadata.
DenyAllApproval: Provider that denies all operations (useful for read-only/audit contexts).
ExponentialBackoffRetry: Exponential-backoff retry provider.
HandlerFacade: A facade that projects a CGP-wired context as a ToolHandler trait object.
InteractiveCtx: Interactive runtime context — used during normal TUI sessions.
NoCache: No-op cache provider for contexts that should always execute directly.
NoLogging: No-op logging provider for contexts that don’t need telemetry.
NoRetry: No-op retry provider for contexts that should fail fast.
NoSandbox: No-sandbox provider for trusted/test contexts.
PassthroughExecutor: Passthrough executor — delegates to a stored Arc<dyn Tool>.
PassthroughMetadata: Metadata provider that delegates to an inner Tool.
PromptApproval: Prompt-based approval provider for interactive sessions.
RetryPolicy: Retry policy shared by CGP retry providers.
ToolBridgeCtx: Bridge context: combines a runtime context with shared tool ownership.
ToolExecutionCacheKey: Cache key for tool execution results.
ToolFacade: A facade that projects a CGP-wired context as a Tool trait object.
TracingLogging: Logging provider that traces tool execution lifecycle.
TypedToolCtx: Typed CGP context that carries a concrete tool instance plus runtime policy.
TypedToolExecutor: Execute provider that dispatches directly to a typed tool instance.
TypedToolMetadata: Metadata provider that dispatches directly to a typed tool instance.
WorkspaceSandbox: Workspace-scoped sandbox provider.

Enums§

ApprovalComponent: Component for approval/permission checks before tool execution.
CacheComponent: Component for cached tool results.
ExecuteComponent: Component for the core tool execution logic.
LoggingComponent: Component for execution logging and telemetry.
MetadataComponent: Component for tool metadata (name, description, schemas).
OutputMapComponent: Component for mapping between output formats (JSON ↔ dual-channel, etc.).
RetryComponent: Component for retry policy around tool execution.
SandboxComponent: Component for sandbox policy selection and enforcement.
SessionComponent: Component for session/turn context creation.

Traits§

ApprovalProvider: Provider trait for approval/permission checks.
CacheProvider: Provider trait for cached tool results.
CanApproveTool
CanExecuteTool
CanProvideToolMetadata
CanResolveSandbox
ExecuteProvider: Provider trait for tool execution (the core “handle” operation).
HasComponent: Type-level lookup: maps a component Name to a concrete Provider type for a given implementor (the “context”).
HasExecutionCaches: Trait for contexts that expose JSON and dual-result caches.
HasInnerTool: Trait for contexts that can borrow an inner Tool for passthrough.
HasRetryPolicy: Trait for contexts that expose retry configuration.
HasToolInstance: Trait for contexts that carry a concrete tool instance.
HasToolRef: Trait for contexts that can expose a tool reference for delegated metadata, validation, and execution.
HasWorkspaceRoot: Trait for contexts that expose a workspace root path.
LoggingProvider: Provider trait for execution logging and telemetry.
MetadataProvider: Provider trait for tool metadata.
OutputMapProvider: Provider trait for output format mapping.
RetryProvider: Provider trait for retry behavior around tool execution.
SandboxProvider: Provider trait for sandbox policy resolution.

Functions§

wrap_native_tool_ci: Wrap a concrete tool instance in a CI CGP facade without erasing it to Arc<dyn Tool> first.
wrap_native_tool_interactive: Wrap a concrete tool instance in an interactive CGP facade without erasing it to Arc<dyn Tool> first.
wrap_tool_ci: Create a ToolFacade that wraps an existing Arc<dyn Tool> with CGP-wired auto-approval and no middleware for CI contexts.
wrap_tool_interactive: Create a ToolFacade that wraps an existing Arc<dyn Tool> with CGP-wired approval, sandbox, and middleware for interactive sessions.

Type Aliases§

ComponentProvider: The elaborated provider/dictionary selected by Ctx for component Name.
StrictWorkspaceSandbox: Strict sandbox that enforces workspace boundaries in CI.