Crate gestalt

Expand description

§Gestalt Rust SDK

Use the Rust SDK to build compiled Gestalt providers with typed routers, serde input and output types, and schema-derived catalog metadata.

The package is published to crates.io as gestalt-sdk, while Rust code imports the crate as gestalt.

cargo add gestalt-sdk --rename gestalt
cargo add serde --features derive
cargo add schemars --features derive

§Quick start

Register typed operations on a router. The router dispatches requests and emits catalog metadata for gestaltd.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use std::sync::Arc;

#[derive(Default)]
struct SearchProvider;

#[gestalt::async_trait]
impl gestalt::Provider for SearchProvider {}

#[derive(Deserialize, JsonSchema)]
struct SearchInput {
    #[schemars(description = "Search query")]
    query: String,
}

#[derive(Serialize, JsonSchema)]
struct SearchOutput {
    results: Vec<String>,
}

fn router() -> gestalt::Result<gestalt::Router<SearchProvider>> {
    gestalt::Router::new().register(
        gestalt::Operation::<SearchInput, SearchOutput>::new("search")
            .method("GET")
            .title("Search"),
        |_: Arc<SearchProvider>, input, _request| async move {
            Ok::<_, gestalt::Error>(gestalt::ok(SearchOutput {
                results: vec![input.query],
            }))
        },
    )
}

gestalt::export_provider!(constructor = SearchProvider::default, router = router);

Fields are required unless they are modeled as Option<T> or have a serde default. Use schemars attributes for catalog descriptions.

§Provider surfaces

Use Provider, Operation, Router, and export_provider! for integration providers. Use the other provider traits and export macros when you are serving a host-service backend.

Trait	Export macro	Use it when you want to serve
`AuthenticationProvider`	`export_authentication_provider!`	Login flows.
`CacheProvider`	`export_cache_provider!`	Plugin-bound cache storage.
`S3Provider`	`export_s3_provider!`	S3-compatible object storage.
`SecretsProvider`	`export_secrets_provider!`	Secret resolution.
`WorkflowProvider`	`export_workflow_provider!`	Workflow runs, schedules, and event triggers.
`AgentProvider`	`export_agent_provider!`	Agent sessions, turns, events, interactions, and capabilities.
`PluginRuntimeProvider`	`export_plugin_runtime_provider!`	Hosted plugin execution backends.

The crate also exposes clients for sibling host services, including Cache, S3, WorkflowHost, WorkflowManager, AgentHost, AgentManager, and PluginInvoker.

§Codegen strategy

Bindings are checked into src/generated so crate consumers do not need a protobuf toolchain when building gestalt-sdk.

Maintainers regenerate them from the shared proto definitions in sdk/proto with the Buf template in sdk/proto/buf.rust.gen.yaml. Use the same Buf CLI version as CI for deterministic remote-plugin output.

To regenerate the bindings:

sdk/rust/scripts/generate_stubs.sh

§Public surface

The crate keeps generated bindings behind a higher-level authoring API:

Provider, Request, Response, and ok(...) model integration providers.
Router and Operation register typed operations and derive catalog metadata from serde and schemars.
AuthenticationProvider, CacheProvider, S3Provider, SecretsProvider, WorkflowProvider, AgentProvider, and PluginRuntimeProvider model executable provider runtimes.
Cache, S3, WorkflowHost, WorkflowManager, AgentHost, AgentManager, and PluginInvoker call sibling host services.
RuntimeMetadata lets provider runtimes describe their display metadata and version.
runtime contains entrypoints for serving provider surfaces over the Unix socket exposed by gestaltd.
proto::v1 exposes generated protocol bindings for low-level integration work.

§Package layout

This package intentionally lives outside the existing gestalt/ Cargo workspace so the SDK can evolve independently of the CLI crate graph.

Re-exports§

pub use indexeddb::Cursor;
pub use indexeddb::CursorDirection;
pub use indexeddb::ENV_INDEXEDDB_SOCKET;
pub use indexeddb::IndexedDB;
pub use indexeddb::IndexedDBError;
pub use indexeddb::Transaction;
pub use indexeddb::TransactionDurabilityHint;
pub use indexeddb::TransactionIndexClient;
pub use indexeddb::TransactionMode;
pub use indexeddb::TransactionObjectStore;
pub use indexeddb::TransactionOptions;
pub use indexeddb::indexeddb_socket_env;
pub use indexeddb::indexeddb_socket_token_env;
pub use s3::ENV_S3_SOCKET;
pub use s3::ENV_S3_SOCKET_TOKEN;
pub use s3::S3;
pub use s3::S3Error;
pub use s3::S3Provider;
pub use s3::s3_socket_env;
pub use s3::s3_socket_token_env;

Modules§

indexeddb: IndexedDB-style datastore client and provider helpers.
proto: Generated protobuf and gRPC bindings for the Gestalt provider protocol.
runtime: Runtime entrypoints for serving Gestalt provider surfaces over Unix sockets.
s3: S3-compatible client and provider helpers.
telemetry: OpenTelemetry helpers for provider-authored GenAI instrumentation. OpenTelemetry helpers for provider-authored GenAI instrumentation.

Macros§

export_agent_provider: Exports the agent-provider entrypoint expected by gestaltd.
export_authentication_provider: Exports the authentication-provider entrypoint expected by gestaltd.
export_cache_provider: Exports the cache-provider entrypoint expected by gestaltd.
export_plugin_runtime_provider: Exports the plugin-runtime-provider entrypoint expected by gestaltd.
export_provider: Exports the integration-provider entrypoints expected by gestaltd.
export_s3_provider: Exports the S3-provider entrypoint expected by gestaltd.
export_secrets_provider: Exports the secrets-provider entrypoint expected by gestaltd.
export_workflow_provider: Exports the workflow-provider entrypoint expected by gestaltd.

Structs§

Access: Summarizes the host-side access decision attached to an operation.
AgentHost: Client for the agent host service available inside agent providers.
AgentManager: Client for managing agent sessions, turns, events, and interactions.
AuthenticatedUser: AuthenticatedUser is the normalized user identity returned by an authentication provider after a login or token-validation flow.
BeginLoginRequest: BeginLoginRequest starts an interactive login flow.
BeginLoginResponse: BeginLoginResponse returns the provider-managed authorization URL and opaque provider state that must be preserved until completion.
Cache: Client for a running cache provider.
CacheEntry: One cache entry written through Cache::set_many.
CacheSetOptions: Options applied to cache writes.
CompleteLoginRequest: CompleteLoginRequest finishes an interactive login flow.
Credential: Describes the resolved credential used to authorize an operation.
Error: Error returned by typed provider handlers and runtime helpers.
Host: Describes public host metadata attached to a request.
InvocationGrant: Grant included when exchanging an invocation token for a child token.
InvokeOptions: Options that select the target connection for a plugin invocation.
Operation: Describes one statically declared executable operation.
PluginInvoker: Client for invoking sibling plugin operations through the host.
Request: Carries execution-scoped metadata into typed operation handlers.
Response: Wraps a typed handler response plus an optional explicit HTTP status code.
Router: Dispatches typed operations and exposes the corresponding static catalog.
RuntimeLogHost: Client for appending plugin-runtime logs to the host.
RuntimeMetadata: Describes provider metadata that should be surfaced by the runtime.
Subject: Identifies the caller that initiated an operation.
WorkflowHost: Client for invoking operations from workflow provider code.
WorkflowManager: Client for starting workflow runs and managing schedules or triggers.

Enums§

AgentHostError: Errors returned by AgentHost.
AgentManagerError: Errors returned by AgentManager.
CacheError: Errors returned by the cache client transport.
PluginInvokerError: Errors returned by PluginInvoker.
RuntimeLogHostError: Errors returned by RuntimeLogHost.
WorkflowHostError: Errors returned by WorkflowHost.
WorkflowManagerError: Errors returned by WorkflowManager.

Constants§

CURRENT_PROTOCOL_VERSION: Current Gestalt provider protocol version spoken by this SDK.
ENV_AGENT_HOST_SOCKET: Environment variable containing the agent-host service target.
ENV_AGENT_HOST_SOCKET_TOKEN: Environment variable containing the optional agent-host relay token.
ENV_AGENT_MANAGER_SOCKET: Environment variable containing the agent-manager host-service target.
ENV_AGENT_MANAGER_SOCKET_TOKEN: Environment variable containing the optional agent-manager relay token.
ENV_CACHE_SOCKET: Default Unix-socket environment variable used by Cache::connect.
ENV_CACHE_SOCKET_TOKEN: Default relay-token environment variable used by Cache::connect.
ENV_PLUGIN_INVOKER_SOCKET: Environment variable containing the plugin-invoker host-service target.
ENV_PLUGIN_INVOKER_SOCKET_TOKEN: Environment variable containing the optional plugin-invoker relay token.
ENV_PROVIDER_SOCKET: Unix socket path exposed by gestaltd for the main integration-provider surface.
ENV_RUNTIME_LOG_HOST_SOCKET: Environment variable containing the runtime-log host-service target.
ENV_RUNTIME_LOG_HOST_SOCKET_TOKEN: Environment variable containing the optional runtime-log relay token.
ENV_RUNTIME_SESSION_ID: Environment variable containing the current plugin-runtime session id.
ENV_WORKFLOW_HOST_SOCKET: Environment variable containing the workflow-host service socket path.
ENV_WORKFLOW_MANAGER_SOCKET: Environment variable containing the workflow-manager host-service target.
ENV_WORKFLOW_MANAGER_SOCKET_TOKEN: Environment variable containing the optional workflow-manager relay token.

Traits§

AgentProvider: Provider trait for serving the Gestalt agent-provider protocol.
AuthenticationProvider: Lifecycle and login contract for Gestalt authentication providers.
CacheProvider: Lifecycle and RPC contract for cache providers.
PluginRuntimeProvider: Provider trait for serving hosted plugin-runtime sessions.
Provider: Shared lifecycle contract for Gestalt integration providers.
SecretsProvider: Lifecycle and lookup contract for secrets providers.
WorkflowProvider: Provider trait for serving the Gestalt workflow-provider protocol.

Functions§

cache_socket_env: Returns the environment variable used for a named cache socket.
cache_socket_token_env: Returns the environment variable used for a named cache relay token.
ok: Returns a successful JSON response with status code 200.
runtime_session_id: Returns the current runtime session id from GESTALT_RUNTIME_SESSION_ID.

Type Aliases§

Catalog: Generated catalog schema used by the provider runtime.
CatalogOperation: Generated catalog operation schema.
Result: Convenient result alias for Gestalt SDK operations.
RuntimeLogStream: Runtime log stream enum generated from the provider protocol.

Attribute Macros§

async_trait

Crate gestalt

Crate gestalt Copy item path

§Gestalt Rust SDK

§Quick start

§Provider surfaces

§Codegen strategy

§Public surface

§Package layout

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate gestalt