kcode_k1_ktool_docs/

lib.rs

#![forbid(unsafe_code)]

use serde::{Deserialize, Serialize};

const INVALID_ARGUMENTS: &str = "invalid KtoolDocs arguments";
const UNKNOWN_KTOOL: &str = "unknown Ktool";

struct Entry {
    name: &'static str,
    docs: &'static str,
}

impl Entry {
    const fn new(name: &'static str, docs: &'static str) -> Self {
        Self { name, docs }
    }
}

const RUST_CODE_CREATE: &str = r#"Invoke as RustCodeCreate with arguments matching exactly this JSON Schema: {"type":"object","properties":{"library":{"type":"string"}},"required":["library"],"additionalProperties":false}. Example: {"library":"package-name"}. library must be canonical lowercase-kebab. The backend-selected Profile supplies the authority; authority is never a model argument. Create is only for a brand-new authority-qualified library family. It persists a canonical 0.0.0 working source through KTO, emits editable Documentation.md, Cargo.toml, and ordered src/lib.rs Tool Messages, and returns Created unpublished version <24-lowercase-hex-id>. If the family already exists, use RustCodeOpen."#;
const RUST_CODE_DOCS: &str = r#"Invoke as RustCodeDocs with arguments matching exactly this JSON Schema: {"type":"object","properties":{"library":{"type":"string"},"version":{"type":"string"}},"required":["library"],"additionalProperties":false}. Examples: {"library":"package-name"}, {"library":"package-name","version":"1.2.3"}, or {"library":"package-name","version":"0123456789abcdef01234567"}. library is canonical lowercase-kebab. version, when supplied, is either a canonical stable SemVer selecting an exact published version or a canonical 24-lowercase-hex unpublished ID. The backend-selected Profile supplies authority. Without version, Docs always returns the greatest published SemVer and never an unpublished head. Success returns a Published/Unpublished version heading, a blank line, and exact Documentation.md. It does not establish an editable snapshot or mutate source."#;
const RUST_CODE_OPEN: &str = r#"Invoke as RustCodeOpen with arguments matching exactly this JSON Schema: {"type":"object","properties":{"library":{"type":"string"},"version":{"type":"string"}},"required":["library"],"additionalProperties":false}. Examples: {"library":"package-name"}, {"library":"package-name","version":"1.2.3"}, or {"library":"package-name","version":"0123456789abcdef01234567"}. library is canonical lowercase-kebab. version, when supplied, is either a canonical stable SemVer or a canonical 24-lowercase-hex unpublished ID. The backend-selected Profile supplies authority. Without version, Open selects the current family head: the most recently written unpublished branch after the last publication, otherwise the greatest published SemVer. It emits editable Documentation.md, Cargo.toml, and ordered src/lib.rs Tool Messages and returns the exact opened selector. Published source is public; unpublished source is access-controlled."#;
const RUST_CODE_OVERWRITE: &str = r#"Invoke as RustCodeOverwrite with arguments matching exactly this JSON Schema: {"type":"object","properties":{"box_id":{"type":"integer","minimum":1},"contents":{"type":"string"}},"required":["box_id","contents"],"additionalProperties":false}. Example: {"box_id":42,"contents":"complete replacement contents"}. box_id identifies one original editable Tool Message in the active Rust source. contents completely replaces that segment. Every successful call persists the complete resulting source through KTO. The first overwrite of published source creates and returns a new unpublished 24-hex ID; later overwrites retain that ID. Stale revisions fail. Multiple unpublished branches may coexist. If the affected complete file lacks a trailing LF, K1 appends exactly one; an existing LF, including CRLF, is unchanged."#;
const RUST_CODE_CHECK: &str = r#"Invoke as RustCodeCheck with arguments matching exactly this JSON Schema: {"type":"object","properties":{"box_id":{"type":"integer","minimum":1}},"required":["box_id"],"additionalProperties":false}. Example: {"box_id":42}. box_id identifies any original editable Tool Message in the active Rust source. Every call runs a fresh complete check against the exact active source. It changes only disposable check state, returns Check passed. or complete failure text, and does not mutate or publish source."#;
const RUST_CODE_PUBLISH: &str = r#"Invoke as RustCodePublish with arguments matching exactly this JSON Schema: {"type":"object","properties":{"box_id":{"type":"integer","minimum":1},"version":{"type":"string"}},"required":["box_id","version"],"additionalProperties":false}. Example: {"box_id":42,"version":"1.2.3"}. box_id identifies the active Rust source and version is a canonical stable SemVer unused in that authority/library family. The SemVer is declared only at publication. K1 rewrites only [package].version in an exact publication candidate, checks that candidate, preserves it as an Object, reauthorizes immediately before the KTO publication effect, and leaves the unpublished source unchanged. Success returns Published version <semver>. An already-used SemVer is rejected even for identical source."#;
const RUST_CODE_BUILD: &str = r#"Invoke as RustCodeBuild with arguments matching exactly this JSON Schema: {"type":"object","properties":{"library":{"type":"string"},"version":{"type":"string"}},"required":["library","version"],"additionalProperties":false}. Example: {"library":"loom","version":"0.1.0"}. library is canonical lowercase-kebab and version is one exact canonical published stable SemVer. The backend-selected Profile supplies authority; authority is never a model argument. Build selects only that published source, uses library as the binary target name, and runs cargo build --release --locked --bin <library>. Success returns the authority-qualified source identity, version, and disposable server code-cache path. It creates no Object or durable binary publication and does not deploy, restart, or execute the binary."#;

const WEB_CODE_CREATE: &str = r#"Invoke as WebCodeCreate with arguments matching exactly this JSON Schema: {"type":"object","properties":{"library":{"type":"string"},"language":{"type":"string","enum":["javascript","html","css"]}},"required":["library","language"],"additionalProperties":false}. Example: {"library":"package-name","language":"javascript"}. library is canonical lowercase-kebab. The backend-selected Profile supplies authority. Create is only for a brand-new family with no published or unpublished source. It persists an empty versionless source through KTO, emits editable Documentation.md and code Tool Messages, and returns its stable 24-lowercase-hex unpublished ID. Existing families must use WebCodeOpen."#;
const WEB_CODE_DOCS: &str = r#"Invoke as WebCodeDocs with arguments matching exactly this JSON Schema: {"type":"object","properties":{"library":{"type":"string"},"version":{"type":"string"}},"required":["library"],"additionalProperties":false}. Examples: {"library":"package-name"}, {"library":"package-name","version":"1.2.3"}, or {"library":"package-name","version":"0123456789abcdef01234567"}. version, when supplied, is canonical stable SemVer or a canonical unpublished 24-lowercase-hex ID. The backend-selected Profile supplies authority. Without version, Docs returns only the greatest published SemVer and never an unpublished workspace. Success emits exact Documentation.md and reports the selected version without establishing editable state."#;
const WEB_CODE_OPEN: &str = r#"Invoke as WebCodeOpen with arguments matching exactly this JSON Schema: {"type":"object","properties":{"library":{"type":"string"},"version":{"type":"string"}},"required":["library"],"additionalProperties":false}. Examples: {"library":"package-name"}, {"library":"package-name","version":"1.2.3"}, or {"library":"package-name","version":"0123456789abcdef01234567"}. Open never creates. With version it opens that exact published or access-authorized unpublished source. Without version it opens the most recently updated unpublished workspace when its authored bytes are not published; otherwise it opens the greatest published SemVer. It emits editable Documentation.md and code Tool Messages and reports the selected version."#;
const WEB_CODE_OVERWRITE: &str = r#"Invoke as WebCodeOverwrite with arguments matching exactly this JSON Schema: {"type":"object","properties":{"box_id":{"type":"integer","minimum":1},"contents":{"type":"string"}},"required":["box_id","contents"],"additionalProperties":false}. Example: {"box_id":42,"contents":"complete replacement contents"}. box_id identifies one original editable Tool Message in the active Web source. contents completely replaces that documentation or code part without normalization. Every successful call submits one KTO transaction, including byte-identical replacements. Editing published or already-published bytes creates a new unpublished ID; later dirty edits retain that ID and advance its revision. Multiple unpublished versions may coexist."#;
const WEB_CODE_CHECK: &str = r#"Invoke as WebCodeCheck with arguments matching exactly this JSON Schema: {"type":"object","properties":{"box_id":{"type":"integer","minimum":1}},"required":["box_id"],"additionalProperties":false}. Example: {"box_id":42}. box_id identifies any original editable Tool Message in the active Web source. Every call runs a fresh complete Chromium check against the exact active source. Drafts use an internal deterministic check version. Check does not mutate source, publish, or provide reusable proof for a later SemVer."#;
const WEB_CODE_PUBLISH: &str = r#"Invoke as WebCodePublish with arguments matching exactly this JSON Schema: {"type":"object","properties":{"box_id":{"type":"integer","minimum":1},"version":{"type":"string"}},"required":["box_id","version"],"additionalProperties":false}. Example: {"box_id":42,"version":"1.2.3"}. box_id identifies the active Web source and version is canonical stable SemVer unused in that authority/library family. SemVer is declared only here. K1 generates k1-web.json for that exact version, runs a fresh check, preserves the exact source Object, reauthorizes disclosure, and submits one immutable public release. It does not deploy or restart."#;

static CATALOG: [Entry; 27] = [
    Entry::new(
        "KtoolDocs",
        r#"Invoke as KtoolDocs {"name":"<exact Ktool name>"}. Arguments contain exactly one nonempty string. Matching is exact and case-sensitive. Success returns compact JSON with name, latest_version, docs, deprecated, and replacement. The operation does not list, search, suggest, authorize, register, or prove live availability."#,
    ),
    Entry::new(
        "CurrentTime",
        r#"Invoke as CurrentTime {}. Returns current system UTC in RFC3339 with exactly three fractional digits and Z. Any nonempty or nonobject arguments are invalid. It is stateless."#,
    ),
    Entry::new(
        "KmapCreateNode",
        r#"Invoke as KmapCreateNode {"title":string,"navigation_hint":string,"narrative":string,"connections":[string,...]}. Connections are exact 24-lowercase-hex node IDs. Using active Kmap authorization, it creates one node, adds Navigation connections, marks it loaded, and returns its ID."#,
    ),
    Entry::new(
        "KmapOpenNode",
        r#"Invoke as KmapOpenNode {"node_id":string,"budget":number}. node_id is exact 24-lowercase-hex and budget finite nonnegative. It opens Full mode at temperature 1, tracks first-pull provenance, and returns only components not already returned this session."#,
    ),
    Entry::new(
        "KmapUpdateNode",
        r#"Invoke as KmapUpdateNode {"node_id":string,"title":string,"navigation_hint":string,"narrative":string,"connections":[string,...]}. IDs are exact 24-lowercase-hex. It replaces text fields, additively upserts Navigation connections, and marks the node loaded."#,
    ),
    Entry::new(
        "KmapPenalizeNodes",
        r#"Invoke as KmapPenalizeNodes {"node_ids":[string,...]}. IDs are exact 24-lowercase-hex. It deduplicates and applies one noncritical negative measurement to each newly eligible loaded node with first-pull provenance; those nodes are excluded from later KmapConnectNodes."#,
    ),
    Entry::new(
        "KmapConnectNodes",
        r#"Invoke as KmapConnectNodes {}. Using active Kmap authorization, it adds every missing directed Automated connection among loaded unpenalized session nodes. Existing connections remain and self-connections are omitted."#,
    ),
    Entry::new(
        "SendMessage",
        r#"Invoke as SendMessage {"message":string}. The single message must be nonempty. It durably appends one visible Agent Message to the authenticated current conversation and leaves the provider turn open. It has no cross-conversation or network destination."#,
    ),
    Entry::new(
        "WebSearch",
        r#"Invoke as WebSearch {"query":string,"model":"codex/<model>","reasoning_effort":string?}. model requires the exact case-sensitive codex/ prefix; effort defaults to medium. It starts one isolated asynchronous search with a 60-minute deadline. Metadata does not authorize or prove provider availability."#,
    ),
    Entry::new(
        "GetLaunchNode",
        r#"Invoke as GetLaunchNode with arguments matching exactly this JSON Schema: {"type":"object","properties":{"authority_kind":{"type":"string","enum":["user","group"]},"authority_id":{"type":"string"},"target":{"type":"string"}},"required":["authority_kind","authority_id","target"],"additionalProperties":false}. Example: {"authority_kind":"user","authority_id":"0123456789abcdef01234567","target":"KmapLaunchNode"}. authority_id is one canonical 24-lowercase-hex UserId or GroupId and target is exact and case-sensitive. The caller's active Access context independently authorizes the selected authority's launch binding and referenced Kmap node. Success returns compact JSON {"node_id":"<visible 24-lowercase-hex AccessId>"}. It does not load, create, set, delete, list, search, or otherwise mutate nodes or bindings."#,
    ),
    Entry::new(
        "SetLaunchNode",
        r#"Invoke as SetLaunchNode {"target":string,"node_id":string}. target is exact and node_id a visible 24-lowercase-hex AccessId. With current-user authority, it creates or updates that target's launch-node reference."#,
    ),
    Entry::new(
        "ListContacts",
        r#"Invoke as ListContacts {}. Returns the complete caller-owned Known Contacts union with user_id, username, person_id, full_name, and nullable kmap_launch_node."#,
    ),
    Entry::new(
        "ListGroups",
        r#"Invoke as ListGroups {}. Returns visible ordinary human memberships excluding Known Contacts and filtered groups, with group_id, name, revision, caller_role, and kmap_launch_node, and no counts."#,
    ),
    Entry::new(
        "GetGroup",
        r#"Invoke as GetGroup {"group_id":string}. User-or-active-model visibility suffices. Returns group_id, name, revision, kmap_launch_node, users, and models; user rows contain user_id, username, person_id, full_name, role, kmap_launch_node; model rows contain model_id and nullable name. No messages or counts."#,
    ),
    Entry::new("RustCodeCreate", RUST_CODE_CREATE),
    Entry::new("RustCodeDocs", RUST_CODE_DOCS),
    Entry::new("RustCodeOpen", RUST_CODE_OPEN),
    Entry::new("RustCodeOverwrite", RUST_CODE_OVERWRITE),
    Entry::new("RustCodeCheck", RUST_CODE_CHECK),
    Entry::new("RustCodePublish", RUST_CODE_PUBLISH),
    Entry::new("RustCodeBuild", RUST_CODE_BUILD),
    Entry::new("WebCodeCreate", WEB_CODE_CREATE),
    Entry::new("WebCodeDocs", WEB_CODE_DOCS),
    Entry::new("WebCodeOpen", WEB_CODE_OPEN),
    Entry::new("WebCodeOverwrite", WEB_CODE_OVERWRITE),
    Entry::new("WebCodeCheck", WEB_CODE_CHECK),
    Entry::new("WebCodePublish", WEB_CODE_PUBLISH),
];

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Arguments {
    name: String,
}

#[derive(Serialize)]
struct Response<'a> {
    name: &'a str,
    latest_version: &'static str,
    docs: &'a str,
    deprecated: bool,
    replacement: Option<&'a str>,
}

fn find_entry(name: &str) -> Option<&'static Entry> {
    CATALOG.iter().find(|entry| entry.name == name)
}

fn render(entry: &Entry) -> Result<String, String> {
    serde_json::to_string(&Response {
        name: entry.name,
        latest_version: "1.0.0",
        docs: entry.docs,
        deprecated: false,
        replacement: None,
    })
    .map_err(|error| format!("KtoolDocs response serialization failed: {error}"))
}

pub fn is_known_ktool(name: &str) -> bool {
    find_entry(name).is_some()
}

pub fn ktool_docs(arguments: &str) -> Result<String, String> {
    let arguments: Arguments =
        serde_json::from_str(arguments).map_err(|_| INVALID_ARGUMENTS.to_owned())?;
    if arguments.name.is_empty() {
        return Err(INVALID_ARGUMENTS.into());
    }
    render(find_entry(&arguments.name).ok_or_else(|| UNKNOWN_KTOOL.to_owned())?)
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::Value;

    fn query(name: &str) -> String {
        serde_json::json!({"name": name}).to_string()
    }

    #[test]
    fn catalog_is_exact_and_remains_v1() {
        assert_eq!(CATALOG.len(), 27);
        for entry in &CATALOG {
            assert!(is_known_ktool(entry.name));
            let value: Value =
                serde_json::from_str(&ktool_docs(&query(entry.name)).unwrap()).unwrap();
            assert_eq!(value.as_object().unwrap().len(), 5);
            assert_eq!(value["latest_version"], "1.0.0");
            assert_eq!(value["deprecated"], false);
            assert!(value["replacement"].is_null());
        }
        let get = ktool_docs(&query("GetLaunchNode")).unwrap();
        assert!(get.contains("authority_kind"));
        assert!(get.contains("visible 24-lowercase-hex AccessId"));
        assert!(get.contains("does not load"));
    }

    #[test]
    fn code_contracts_freeze_persistent_selector_semantics() {
        assert!(RUST_CODE_CREATE.contains(r#""required":["library"]"#));
        assert!(RUST_CODE_OVERWRITE.contains("Every successful call persists"));
        assert!(RUST_CODE_PUBLISH.contains("declared only at publication"));
        assert!(RUST_CODE_BUILD.contains(r#""required":["library","version"]"#));
        assert!(RUST_CODE_BUILD.contains("cargo build --release --locked"));
        assert!(RUST_CODE_BUILD.contains("creates no Object"));
        assert!(WEB_CODE_CREATE.contains(r#""required":["library","language"]"#));
        assert!(WEB_CODE_DOCS.contains("greatest published SemVer"));
        assert!(WEB_CODE_OPEN.contains("most recently updated unpublished workspace"));
        assert!(WEB_CODE_OVERWRITE.contains("Every successful call submits one KTO transaction"));
        assert!(WEB_CODE_PUBLISH.contains(r#""required":["box_id","version"]"#));
        for docs in [
            WEB_CODE_CREATE,
            WEB_CODE_DOCS,
            WEB_CODE_OPEN,
            RUST_CODE_BUILD,
        ] {
            assert!(!docs.contains(r#""authority":{"type""#));
        }
    }

    #[test]
    fn malformed_and_unknown_arguments_fail_closed() {
        for input in [
            "",
            "null",
            "[]",
            "{}",
            r#"{"name":""}"#,
            r#"{"name":1}"#,
            r#"{"name":"KtoolDocs","extra":false}"#,
            r#"{"name":"KtoolDocs","name":"CurrentTime"}"#,
        ] {
            assert_eq!(ktool_docs(input), Err(INVALID_ARGUMENTS.into()));
        }
        assert_eq!(ktool_docs(&query("Unknown")), Err(UNKNOWN_KTOOL.into()));
        assert!(!is_known_ktool(" WebSearch"));
    }
}