Plugins

In one line

Twelve plugin-* features; each one implements CucaPlugin and no plugin depends on another.

You need

The plugin features you want, named explicitly; none is enabled by default.

Read this if

You need a plugin's feature flag, entry type, hooks, config defaults or caps.

The twelve features

Every plugin attaches with CucaClientBuilder::register_plugin(Arc<dyn CucaPlugin>). The last column lists the hooks where the plugin acts; no bundled plugin overrides execute_local_tool.

plugin-session-log also implements SessionStorePlugin, which adds append_log, replay_session and fork_session.

Headings on every plugin page

Each plugin page answers the same questions under the same headings, in this order:

1. Feature and entry type
2. Hooks
3. Configuration
4. Caps and at-cap policy
5. Errors
6. Example
7. Related pages

Hook order and error handling

Plugins run in registration order at every hook site. A plugin must not require a position relative to another plugin.

• A value returned from execute_local_tool must be a ToolResult whose tool_call_id equals the incoming ToolCall id. A mismatch is PluginError::Validation with schema local tool result.
• A plugin-guardrails build logs a failed on_response_complete through tracing under target cuca::client; other builds drop it.
• A prompt cache hit under service-prompt-cache replays the stored blocks, skips execute_local_tool and on_stream_chunk, and still runs every on_response_complete.
• Recoverable conditions belong in the block itself: guardrails, MCP, sandbox and the other tool plugins replace a ToolCall with a ToolResult instead of returning an error.

Caps and at-cap policies

Every plugin page states its caps as bound, policy at the bound and usage gauge, in that order. The reasoning behind refusing rather than evicting is Memory discipline.

plugin-redaction bounds:

• RedactionConfig::MAX_RULES, 256 rules per policy.
• MAX_PATTERN_BYTES, 512 per literal or prefix; MAX_KIND_BYTES, 32 per kind.
• max_matches_per_text, default 1024, at most MAX_MATCHES_PER_TEXT (4096). A string over it fails with PluginError::HookFailure instead of being truncated.
• MAX_JSON_DEPTH, 64 levels of ToolCall arguments, also refused with HookFailure.
• An empty or over-cap policy is rejected at construction.

plugin-sandbox bounds, per call:

• max_memory_bytes, 64 MiB.
• max_instructions, 1000000.
• timeout_ms, 5000.
• Guest output, 8 MiB, not configurable.
• Nothing accumulates across calls, so no gauge is needed.

No edges between plugins

The plugin tier is flat. Cargo.toml declares no feature edge between plugins, and no plugin references another in code or at runtime.

• Every plugin-* feature depends on core only and builds alone on any one provider.
• A service may depend on a plugin: service-entity-extraction and service-vector-store require plugin-memory, and service-replay requires plugin-session-log. A plugin never depends on, or names, a service.
• Services never implement CucaPlugin; they are explicit-call, and registering one with register_plugin is a compile error.
• The CI job plugin_layering greps every file under src/plugins/ for service-, for crate::services, and for plugins:: paths to prompt_cache, entity_extraction, replay and rate_limit. A cfg(all(...)) reverse edge compiles in both the solo and all-features builds, so only that inspection catches it.

Plugins and services explains the layering.

Shared optional dependencies

Eight optional crates are enabled by more than one feature. A shared crate is a shared dependency, not a feature edge between plugins.

plugin-web-search enables reqwest/rustls itself, so it runs HTTPS searches in a build where no provider feature contributes TLS.

Related pages

• The feature matrix: every feature and its dependencies.
• Error types: PluginError and CucaError.
• Write a custom plugin: implement CucaPlugin yourself.

Per-plugin pages