# Agent Integration Reference
`kcode-rust-libs` is a synchronous Rust library for creating, opening, editing, validating, and publishing small agent-authored Rust libraries. An integrating server supplies its own API transport, authentication, discovery, sessions, concurrency control, and secrets database.
```rust
use kcode_rust_libs::{KcodeRustLibs, RustLibFile, RustLibPath};
let crates_io_token = load_crates_io_token_from_secrets_database()?;
let rust_libs = KcodeRustLibs::new("/srv/kcode-rust-libs", crates_io_token)?;
```
| Call | Result |
|---|---|
| `KcodeRustLibs::new(root, crates_io_registry_token)` | Creates or opens the persistent Rust libraries root and retains the non-empty crates.io token in memory. |
| `rust_libs.create_rust_lib(name)` | Creates a Rust 2024 library and returns it fully loaded. |
| `rust_libs.open_rust_lib(name)` | Opens an existing Rust library and returns every current file. |
| `rust_lib.name()` | Returns the Rust library name. |
| `rust_lib.files()` | Returns sorted `&[RustLibFile]`; each has public `path` and `contents`. |
| `rust_lib.docs()` | Returns `&RustLibDocs` with canonical `version` and `documentation` text. |
| `rust_lib.write(&files)` | Creates or fully overwrites supplied files; omitted files remain. |
| `rust_lib.check()` | Runs formatting, build, Clippy, tests, and doc tests in Podman. |
| `rust_lib.publish()` | Checks, then publishes the root package to crates.io with the initialization token. |
Construct a write with `RustLibFile::new(RustLibPath::new("src/lib.rs")?, complete_text)`. Paths use `/`, are relative, and reject traversal. All paths and files are UTF-8. There is no general deletion, patch, reload, close, listing, or arbitrary-command API.
Every managed Rust library requires root-level `Cargo.toml` and `Documentation.md`. `RustLibDocs.version` is parsed from the root manifest's literal `[package].version`; it must be a canonical stable `major.minor.patch`. Workspace-inherited versions are rejected. `Version.txt` is obsolete and is not created or required. When an older managed library is successfully opened, a legacy root `Version.txt` is removed automatically before the handle is returned.
This crate is itself laid out as a managed Rust library. Place its directory at `<rust-libs-root>/kcode-rust-libs`, open it with `open_rust_lib("kcode-rust-libs")`, and an agent can read or replace its source, tests, specification, and documentation through the same API. Keep generated build output and non-UTF-8 editor artifacts outside the managed directory; `check()` already uses disposable external work and target directories.
`check()` returns code-quality failures as `Ok(CheckResult)` with `passed() == false`; infrastructure failures are `Err`. `publish()` uses the crates.io registry token supplied to `KcodeRustLibs::new`. Surrounding whitespace is discarded and an empty token is rejected during initialization, before the library creates filesystem roots. The token is retained in a private redacted in-memory value, shared with opened handles, and passed only to the final publication container. The library never discovers, reads, creates, or modifies a credential file on disk, so copying the Rust libraries root does not copy publishing authority.
The integrating server must retrieve the token from its secrets database, initialize this library with it, allow only one active handle per Rust library, and drop the handle when the session ends. The server's agent-facing create/open/write/check/publish calls should not expose the token. Run `check()` and `publish()` on a blocking worker in asynchronous servers.