microclaw-sdk 0.31.0

Official Rust SDK for embedding MicroClaw agents, Skills, and Workers
Documentation
# MicroClaw SDK

`microclaw-sdk` is the supported facade for embedding the MicroClaw run lifecycle in a Rust
application. It exposes provider-neutral requests, events, controls, terminal results, Agent
handles, and Worker contracts without pulling in Server, channel, Web, or desktop UI code.

The `minimal` preset is protocol-only, `standard` adds a host-provided `RunExecutor`, and `full`
starts the same skilled Agent Engine used by Server and MicroClaw Code without exposing either product package.
`minimal` does not compile the Agent Engine, HTTP clients, SQLite, Tokio, Typst, or OpenTelemetry.

## Choose a feature set

| Feature | Use it when |
|---|---|
| `minimal` | Your application only needs stable protocol, event, control, and Worker wire contracts |
| `standard` (default) | Your application wants the Runtime, Agent, Run, control, and Local Worker lifecycle |
| `remote-worker` | The host or executor communicates over the authenticated WebSocket Worker protocol |
| `full` | You want the configured MicroClaw Agent Engine, including providers, tools, memory, Skills, MCP, hooks, and Subagents |

Most first-time integrations should use `full`. The workspace minimum supported
Rust version is 1.93.

The `full` preset provides a stable builder and validates selected Skills before a run starts:

```rust,no_run
use microclaw_sdk::MicroClaw;

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let microclaw = MicroClaw::builder("microclaw.config.yaml")
    .caller_channel("my-app")
    .max_concurrent_runs(4)
    .build()
    .await?;
let agent = microclaw
    .agent("reviewer")
    .skill("code-review")
    .build()?;
let result = agent.run("Review this repository").result().await?;
println!("{}", result.final_text);
# Ok(())
# }
```

Applications that do not have a MicroClaw YAML file can configure the provider directly:

```rust,no_run
use microclaw_sdk::{FullRuntimeConfig, MicroClaw};

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let config = FullRuntimeConfig::new("openai", "gpt-5", std::env::var("OPENAI_API_KEY")?);
let microclaw = MicroClaw::configure(config).build().await?;
# Ok(())
# }
```

Use `microclaw.skills()` to list available and unavailable Skills with diagnostics. A `full` host
can install local, GitHub, or ClawHub Skills, enable or disable them, reload the catalog without a
restart, and recoverably remove them with `install_skill`, `set_skill_enabled`, `reload_skills`,
and `remove_skill`. See `examples/managed_skills.rs` for the complete lifecycle.

Durable work delegated by the Main Agent is available through `delegated_tasks`; active tasks can
be cancelled with `cancel_delegated_task`. The typed `DelegatedTaskStatus` is forward-compatible
with future Engine states. See `examples/delegated_tasks.rs`.

For smaller integrations, see `examples/minimal_protocol.rs` for protocol-only integration,
`examples/custom_executor.rs` for a host executor, and `examples/configured_skilled_agent.rs` for
the full configured Agent Engine.

A practical first integration should build one reusable runtime, run one local Agent, consume
ordered events, branch on `RuntimeErrorCode`, verify cancellation, and shut down cleanly. Add
managed Skills and remote Workers only after that baseline works. The
[SDK quickstart](https://microclaw.org/docs/sdk-quickstart) includes a compact acceptance checklist
and common-failure guide.

## Runtime contract

- Build one `MicroClaw` runtime and reuse it across Agents.
- Use an Agent profile for stable identity, prompt, Skills, and tool policy.
- Treat each `RunHandle` as one execution with ordered events, controls, and one
  authoritative terminal `RunResult`.
- Branch on `RuntimeErrorCode` rather than parsing error messages.
- Preserve event sequence numbers when projecting runs into a UI or protocol.
- Call `Runtime::shutdown().await` to stop accepting work and drain active runs.

## Workers

`LocalWorker` uses the same Agent, Run, event, and control contracts. It exposes active and queued
capacity, labels, health, draining, resume, and `wait_for_idle()` for graceful application
shutdown. `Worker::submit` returns an explicit `Unavailable` error while draining or unavailable.
The serialized `WorkerCommand` and `WorkerFrame` types use `WORKER_PROTOCOL_VERSION` for remote
transports. Implement `WorkerTransport` and `WorkerConnection`, then call
`RemoteWorker::connect(...)`; remote runs return the same `RunHandle` used by local execution.
Use `RemoteWorker::connect_with_options(...)` to bound reconnect attempts and tune backoff while
retaining event replay, acknowledgement, duplicate suppression, and pending-control recovery. The
`remote-worker` feature (included by `full`) provides `WebSocketWorkerTransport` and an
authenticated `WorkerHost` for real network execution.

## Guides

- [SDK overview]https://microclaw.org/docs/sdk
- [Quickstart]https://microclaw.org/docs/sdk-quickstart
- [Agents, runs, events, and controls]https://microclaw.org/docs/sdk-concepts
- [Skills in embedded applications]https://microclaw.org/docs/sdk-skills
- [Main Agent delegation]https://microclaw.org/docs/sdk-delegation
- [Local and remote Workers]https://microclaw.org/docs/sdk-workers
- [Features and crate boundaries]https://microclaw.org/docs/sdk-features