Agent Interface

NoKV’s supported Agent-facing surface is the exact 18-tool Workbench contract. The names and semantics are shared across delivery surfaces, while the transport remains a deployment choice.

The supported order is:

1. the native full nokv CLI;
2. the direct Python SDK for in-process callers;
3. the lower-level Rust SDK; and
4. an optional stdio MCP sidecar for hosts that require MCP discovery and JSON-RPC transport.

Downstream Agent systems should normally provide skills that call the native CLI. The optional stdio MCP endpoint delegates to the same transport-free facade and is not a canonical API, required service, or separate state machine. The 18 names define behavior, not a required transport.

Product Boundary

A Workbench is a logical workspace API, not a host-filesystem API. It provides a jailed presentation root, path-shaped artifact discovery, conditional publication, deterministic retry, indexed metadata queries, durable commits, leased snapshots, and durable restore into a new Workbench.

It does not provide a FUSE mount, file descriptors, POSIX identity or locking, arbitrary directory rename, empty-directory identity, or cross-shard atomic filesystem operations. Programs that require local paths use explicit materialize/collect adapters; those sandbox paths are not NoKV namespace identities.

Each Workbench exposes five virtual sections:

input
scripts
outputs
logs
metadata

Tool paths are relative to a section. The adapter rejects absolute paths, empty components, ., .., backslashes, NUL, and duplicate section prefixes. The five sections are logical prefixes rather than stored directories.

Tool Surface

The native CLI accepts every name below under nokv workbench <tool> '<json arguments>'. Direct SDKs expose the same core operations programmatically, and the optional MCP sidecar registers the same names as tools.

Tool	Stable behavior
workbench_create	Create one Workbench and expose the five standard sections; exact retries converge.
workbench_put_file	Create-only when replace=false, replace-only when replace=true; never upsert.
workbench_append	Append after generation compare-and-swap; the returned digest identifies the appended delta.
workbench_edit	Replace an exact UTF-8 string; a byte-identical result does not publish a generation.
workbench_list	Non-recursive, cursor-paginated listing at live state or one snapshot.
workbench_stat	Return a compact metadata card without reading the body.
workbench_read	Shape JSON, YAML, or text records, or return base64 byte ranges.
workbench_grep	Case-insensitive literal matching with bounded OR patterns and an optional basename glob.
workbench_search	Run metadata predicates, sort, projection, and facets within one Workbench or Agent root.
workbench_aggregate	Compute bounded count, sum, average, minimum, maximum, grouping, filtering, and sorting.
workbench_catalog	Discover stable field ids and supported query operators.
workbench_find	Find Workbenches by committed state and literal run-manifest matches.
workbench_commit	Publish a versioned run manifest with deterministic identity and exact replay.
workbench_snapshot	Create a leased point-in-time snapshot of a committed Workbench.
workbench_snapshot_renew	Extend a live snapshot lease; never shorten it.
workbench_snapshot_retire	Retire a root-bound snapshot idempotently.
workbench_snapshot_list	Report snapshot aliases, annotations, lifecycle state, and evidence.
workbench_restore	Restore a snapshot or commit into a new hidden-then-visible Workbench; keep the source unchanged.

Friendly errors, section projection, structured decoding, base64 encoding, exact-string editing, grep matching, and result shaping belong to the Workbench adapter. Physical object keys, Holt keys, owner addresses, and routing records do not appear in the contract.

Generations and Conditional Writes

generation is the caller-visible conditional-write token:

• a successful body publication changes it;
• a failed or byte-identical edit does not;
• if_none_match skips a body whose generation is unchanged;
• replace, edit, and append validate the generation they observed; and
• a snapshot freezes the generation visible at its retained read version.

The metadata core stores a whole-body digest on the resulting immutable revision. workbench_append.digest identifies only the appended bytes, not the whole resulting body.

Commit, Snapshot, and Restore

workbench_commit publishes the canonical metadata/run_manifest.json projection. Its identity binds the Workbench, caller-supplied content digest, and canonical manifest digest while excluding server time. An exact retry returns the same durable result. Explicit replacement cannot reinterpret an older retry against a newer head.

A snapshot is a leased MVCC recovery point, not a permanent archive. Long-lived reuse belongs in a durable commit or a compare-and-swap protected tag.

Restore is source-preserving, destination-creating, and same-root/same-shard. It stages a fresh Workbench incarnation and exact revision references, verifies the member closure, then publishes visibility in one final transition. A failed staging operation does not leak into normal reads or queries.

Pagination and Consistency

List, grep, and query cursors are opaque and scope-bound. They bind the RootId, Workbench, normalized prefix or query, snapshot/live selector, continuation fence, and last returned item.

Snapshot continuations stay at one exact retained read version. Live continuations may move to a later read version only while the target Workbench incarnation and revision are unchanged; target drift fails closed. A cursor is not permission to read unretained history.

Contract Evidence

A release is qualified only when both the normalized schema validator and boundary-level result/error tests pass. Schema validation alone proves tool names and input shapes, not durability, recovery, lifecycle, or provider behavior.

Conformance covers all 18 names, typed errors, jail and section projection, generation/digest relationships, commit replay, snapshot lifecycle, restore staging and replay, and paginated result ordering.

Archived Benchmark Profile: Seven Verbs

The agent-interface benchmark preserves an earlier generic seven-verb profile — ls, stat, catalog, find, aggregate, read, and grep — so its published measurements remain interpretable. That profile is archived benchmark material, not the current NoKV Agent API and not an alternative source of truth for the Workbench contract.

Historical trait and implementation names from that benchmark are therefore intentionally omitted here. Current integrations should use the 18-tool Workbench surface through the CLI or direct SDKs, adding the optional MCP sidecar only when the host requires it.