Crate kindling_client 

Rust client for the kindling daemon.

A thin, async HTTP/1-over-Unix-domain-socket client for the kindling-server daemon. It speaks the v1 wire contract exactly, sending the X-Kindling-Project header on every data endpoint, and auto-spawns kindling serve --daemonize on first call if the daemon is not running.

The method surface mirrors kindling-service for ergonomic in-process / via-daemon interchangeability. To stay thin, the crate depends only on kindling_types for domain shapes — never on kindling-service or kindling-store (which pull rusqlite).

v1 wire contract

GET    /v1/health                  → 200 { version, schemaVersion, supportedKinds, storagePath, kindRegistry, projects: [...] }
POST   /v1/capsules                → 201 Capsule
GET    /v1/capsules/open?sessionId → 200 Capsule | null
PATCH  /v1/capsules/:id/close      → 200 Capsule
POST   /v1/observations            → 201 Observation
POST   /v1/observations/list       → 200 ListObservationsResult (paginated)
POST   /v1/observations/:id/forget  → 204 (redact an observation)
POST   /v1/retrieve                → 200 RetrieveResult
POST   /v1/pins                    → 201 Pin
DELETE /v1/pins/:id                → 204
POST   /v1/context/session-start   → 200 { additionalContext: string | null }
POST   /v1/context/pre-compact     → 200 { additionalContext: string | null }

Schema version

Client::health checks the daemon’s reported schemaVersion against ClientConfig::expected_schema_version (default EXPECTED_SCHEMA_VERSION, sourced at compile time from the repo-root schema/version.json) and returns ClientError::SchemaMismatch on disagreement. See Spawner and the config notes for the cargo publish copy-step caveat.

Example

// Everything you need is re-exported here — no need to depend on
// `kindling-types` directly.
use kindling_client::{Client, CapsuleType, ScopeIds};

let client = Client::new()?;
let health = client.health().await?;
println!("daemon schema v{}", health.schema_version);

let capsule = client
    .open_capsule(CapsuleType::Session, "investigate bug", ScopeIds::default(), None)
    .await?;

Re-exports

pub use spool::SpoolConfig;

pub use spool::SpoolError;

pub use spool::SpoolStatus;

pub use spool::SpooledClient;

Modules

spool

A thin, opt-in durable-emit layer over crate.

Structs

AppendResult

Outcome of Client::append_observation.

CandidateResult

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Candidate (observation or summary) ranked by score.

Capability

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Capability block surfaced by health and kindling status --json.

Capsule

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Bounded unit of meaning grouping related observations.

Client

A thin async client for the kindling daemon.

ClientConfig

Configuration for a Client.

CloseCapsuleBody

PATCH /v1/capsules/:id/close body — all fields optional.

CreatePinBody

POST /v1/pins body — create a pin.

Health

Result of GET /v1/health.

KindRegistryEntry

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. One entry in the machine-readable kind registry.

ListObservationsRequest

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Filter + pagination for an observation list request.

ListObservationsResult

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. One page of observations in stable (ts ASC, id ASC) order.

Observation

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Atomic, immutable record of an event captured during development.

ObservationInput

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Input for creating a new observation. Optional fields are auto-generated.

Pin

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Pinned reference to an observation or summary.

PinResult

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Pin together with the observation or summary it points at.

ProviderSearchOptions

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Search options for a retrieval provider.

ProviderSearchResult

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. A single result from a retrieval provider.

RetrieveOptions

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Options for a retrieval request.

RetrieveProvenance

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Provenance for a retrieval result.

RetrieveResult

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Complete retrieval result: pins, optional current summary, ranked candidates, provenance.

ScopeIds

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Scope identifiers for multi-dimensional isolation.

Summary

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. High-level description of a capsule’s content (typically LLM-generated).

Enums

CapsuleStatus

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Capsule lifecycle status.

CapsuleType

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Types of capsules.

ClientError

Errors returned by Client operations.

ObservationKind

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Types of observations that can be captured.

PinTargetType

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Type of entity that can be pinned.

RetrievedEntity

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. An entity returned from retrieval — either an observation or a summary. Untagged so the wire format matches the TS structural union Observation | Summary.

Spawner

How the client starts the daemon when it is not already running.

Transport

Which transport the client uses to reach the daemon.

Constants

EXPECTED_SCHEMA_VERSION

The canonical schema version this client expects the daemon to report.

PROJECT_HEADER

Header carrying the project root string for per-project DB routing. Mirrors kindling_server::PROJECT_HEADER.

Functions

build_capability

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Assemble the capability block from runtime inputs (version, schema, storage path).

default_port_path

Default daemon TCP port file path: ~/.kindling/kindling.port.

default_socket_path

Default daemon socket path: ~/.kindling/kindling.sock.

default_spawn_log_path

Default spawn-failure log: ~/.kindling/spawn.log.

kind_registry

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Machine-readable registry listing every kind with its required fields.

supported_kind_names

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Snake-case kind names for every ObservationKind variant, in declaration order.

Type Aliases

Id

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Unique identifier for entities. Implementation uses UUIDv4 format.

Timestamp

Domain types re-exported from kindling_types so the daemon client is a self-contained SDK: depend on kindling-client alone and reach every type the API sends or returns as kindling_client::<Type>. kindling-types stays an internal transitive dependency you never have to name. Timestamp in epoch milliseconds.