Crate tokitai_core 

Tokitai Core

Core types and traits for the Tokitai AI tool integration library. All tool information is generated at compile time, so the core has zero runtime dependencies and is no_std-compatible (with the serde feature disabled).

See ToolDefinition, ToolProvider, and the tokitai crate for the high-level overview.

Example

use tokitai_core::{ToolDefinition, ParamType};

let tool = ToolDefinition::new(
    "add",
    "Add two numbers together",
    r#"{"type":"object","properties":{"a":{"type":"integer"},"b":{"type":"integer"}},"required":["a","b"]}"#
);
assert_eq!(tool.name, "add");

assert_eq!(ParamType::from_rust_type("i32"), Some(ParamType::Integer));
assert_eq!(ParamType::from_rust_type("Vec<i32>"), Some(ParamType::Array));

Features

Feature	Description
serde (default)	Enable serde/serde_json integration

For no_std usage, depend on the crate with default-features = false.

License

Dual-licensed under either of:

• Apache License, Version 2.0
• MIT License

at your option.

Re-exports

pub use config::ToolConfig;

pub use config::ToolConfigRegistry;

pub use config::GLOBAL_CONFIG_REGISTRY;

pub use dynamic::is_tenant_denied;

pub use dynamic::DynamicHandler;

pub use dynamic::DynamicToolProvider;

pub use dynamic::DynamicToolRegistry;

pub use dynamic::TENANT_DENIED_KIND_HINT;

pub use serde_types::*;

Modules

config

Runtime configuration types used to override compile-time tool metadata. Tool configuration system for runtime tool definition customization.

dynamic

T-010: Dynamic / runtime-mutable tool registry.

serde_types

Re-exports of serde_json and alloc::string types under a stable path. Available when the serde feature is enabled.

Macros

assert_no_config_deadlock

Macro for compile-time deadlock detection.

json_schema

Compile-time helper for emitting JSON Schema strings without runtime overhead.

Structs

AsyncSleep

Runtime-agnostic async sleep future returned by async_sleep.

ToolDefinition

A tool that an AI system can invoke.

ToolError

Error returned by tool invocations.

ToolParameter

A single parameter definition for a tool.

Enums

ParamType

JSON Schema type for a tool parameter.

ToolErrorKind

Classification of a ToolError for structured error handling.

Constants

CONFIG_PRIORITY_DOC

Single source of truth for the priority order of configuration sources that can supply a tool’s description.

CORE_VERSION

T-024: exact version string of tokitai-core that was compiled in (sourced from CARGO_PKG_VERSION). The mcp-server build script writes a generated source file with this constant so the running binary can compare against the version that was baked at compile time.

Traits

AsyncExecutor

Runtime-Agnostic Async Executor

AsyncExecutorExt

Typed convenience wrapper around AsyncExecutor::block_on_dyn. Implemented for every T: AsyncExecutor; re-introduces the natural block_on<F: Future>(&self, F) -> F::Output signature on top of the type-erased entry point.

CapabilityManifestProvider

T-023: trait the #[tool] macro auto-implements for any impl block it processes. Exposes the aggregated CAPABILITIES slice (per-method name + per-method required capability tokens) so the tokitai-mcp-server builder can walk it at start time without depending on a per-impl generated type.

FromJsonValue

From Json Value Trait

ToolCaller

Runtime tool invocation trait. Auto-implemented by the #[tool] macro.

ToolProvider

Compile-time tool registry trait.

Functions

assert_compatible_with

T-024: assert at compile time that the compiled-against tokitai-core matches the expected SemVer string under the standard prefix-match rule (x.y matches x.y.z; x.y.z matches exactly). A mismatch raises a compile_error! naming both versions and the docs.rs migration link.

assert_compatible_with_runtime

T-028: non-const runtime companion to assert_compatible_with.

async_sleep

Sleep for dur without blocking the current thread.

block_on_async

Try to drive future to completion using the registered executor, the current Tokio runtime (when available), or a clear English error.

block_on_async_error_message

Canonical English error message returned by the #[tool] macro when it cannot find any executor to drive a sync-from-async call. The macro embeds the return value of this function as the error string, so the message is centralised here for consistency and future i18n.

block_on_for_executor

T-003 per-call override probe. Returns an executor that should be preferred over the global slot. The macro’s sync-from-async wrapper calls this first; only on None does it fall back to current_async_executor and the active Tokio runtime.

capability_in_allowlist

T-023: returns true when declared is covered by some entry in allowlist. The allowlist supports one wildcard form: a trailing * (e.g. db:read:*) is treated as a prefix match (so db:read:* covers db:read:sales, db:read:any_resource, and any other db:read:<X>). Exact entries (no *) must match the declared capability verbatim. The matcher is case-sensitive: capability tokens are typically lowercase-with-colons in the documented category set, and allowing case folding would weaken the allowlist contract without a clear use case.

clear_current_version

T-013: clear any previously-registered current version. After this call the macro stops gating remove_in until set_current_version is called again. Useful in tests that need to exercise the “no gating” path mid-suite.

current_async_executor

Return the currently registered AsyncExecutor, or None if no executor has been installed via set_async_executor. The returned reference is &'static because the registered Box<dyn AsyncExecutor> is held inside a OnceLock for the program’s lifetime.

current_version

T-013: return the currently registered program version, or None when set_current_version was never called.

from_json_value_generic

Parse a DeserializeOwned value for key. Useful for custom types not covered by the FromJsonValue blanket impls.

from_json_value_str

Borrow a string parameter without copying.

set_async_executor

Install a global AsyncExecutor used by every #[tool]-generated sync wrapper. Call once at program startup, before any sync call_tool is invoked on an async tool. The box is leaked: the executor lives for the lifetime of the program. The first call wins; subsequent calls are silently ignored (best-effort registration).

set_current_version

T-013: install a process-wide current version. The #[tool] macro’s sync wrapper compares this value against each tool’s remove_in field; when remove_in <= current the call returns ToolError::Removed and the user is directed to replaced_by.

Type Aliases

CapabilityManifest

T-023: per-tool capability manifest. Each tuple is (tool_name, required_capabilities). The macro emits an aggregated CAPABILITIES slice per impl block; the server folds those slices into a single CapabilityManifest at startup before walking the allowlist.