@corbet-labs/ccht 0.2.0 → 0.2.2

package/source/README.md

@@ -1,234 +0,0 @@
-# ccht
-
-Reusable conversations for Rust applications, terminals and web frontends.
-**ccht** keeps the conversation model in Rust and compiles
-that same model to Wasm. Native hosts connect to installed agents using the
-[official ACP Rust SDK](https://github.com/agentclientprotocol/rust-sdk).
-
-```text
-Web UI ── @corbet-labs/ccht (Wasm) ── application transport/storage
-                                              │
-TUI / native UI ── ccht::Conversation ── ccht::native ── upstream ACP agent
-```
-
-The library owns structured conversation events, ordered replay, native sessions,
-streaming, cancellation and permission requests. Your application owns its UI,
-instructions, context, tools, user authorization, storage and HTTP/WebSocket/SSE
-transport. No Corbet-specific prompts or database are required.
-
-Agent reasoning, tools, authentication and protocol translation remain upstream.
-ccht does not implement an agent loop, read provider credentials, install agents,
-call paid model HTTP APIs or select an API-key fallback.
-
-## Rust
-
-```toml
-[dependencies]
-ccht = "0.2"
-tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
-```
-
-`native` is the default feature. For the portable model alone:
-
-```toml
-ccht = { version = "0.2", default-features = false }
-```
-
-```rust
-use ccht::{Conversation, Event, WireEvent, acp};
-
-let mut conversation = Conversation::new("workspace/creator");
-conversation.apply(WireEvent::new(
-    "workspace/creator", "turn-1", 1,
-    Event::Update {
-        update: acp::SessionUpdate::AgentMessageChunk(
-            acp::ContentChunk::new("Hello".into()),
-        ),
-    },
-)).unwrap();
-assert_eq!(conversation.turns()[0].text, "Hello");
-```
-
-[examples/native.rs](examples/native.rs) shows streaming from an explicitly
-supplied installed ACP executable. It requires native agent authentication already
-configured by the operator. Use `codex-acp`, `claude-agent-acp`, or `opencode acp`
-as separate, reviewed runtime installations. Generic ACP executables also work.
-No agent/runtime is bundled in the crate or browser package.
-
-`NativeClient::connect` initializes the protocol. Create a session with its working
-directory, explicit model (if desired) and application MCP servers. Take the event
-receiver before prompting and consume it concurrently with the prompt future.
-A session accepts one active prompt; another returns `Busy`. Different sessions
-have separate streams and permission identities. History load/resume and model
-selection require the agent's advertised capabilities; unsupported requests fail.
-
-`session.handle().configuration()` exposes the agent's ordered model, reasoning,
-mode and boolean controls. Call `set_model(id)` or `set_config_option(id, value)`
-to change them. The full response replaces the advertised configuration, including
-dependent options; configuration notifications update both the native handle and
-the portable conversation snapshot. Unknown values fail without a fallback.
-`SessionOptions::configuration` applies explicit settings when creating or restoring
-a session. Retain the agent session ID and its working directory in your product
-storage to resume completed conversations across process restarts. Never replay an
-uncertain delivery automatically.
-
-Permissions default to denial. Applications that opt into asking must render the
-request, check their authority and respond with one of the advertised choices.
-A permission callback is not a sandbox: agent-owned tools may have separate runtime
-policy. Configure filesystem/network confinement in the host for your use case.
-ccht advertises no client filesystem or terminal capabilities.
-
-Cancellation asks the upstream agent to stop. If it does not stop within the
-configured shutdown timeout, ccht closes the SDK connection, affecting **all**
-sessions on that connection. Dropping an active prompt also closes its connection.
-Use one connection per independent workload when cancellation must be isolated.
-Bounded event channels fail explicitly on an unresponsive consumer.
-
-`AgentCommand::with_working_directory` sets the actual agent startup directory
-using installed Linux/macOS `env` launchers. Windows currently reports this helper
-as unsupported because the SDK launch configuration lacks a startup-directory
-field. Session cwd alone does not constrain files read during agent startup.
-Linux is covered by process-level tests; macOS support is source-reviewed.
-
-ACP enables `serde_json`'s `preserve_order` feature through Cargo feature
-unification. Applications that hash or sign JSON must explicitly canonicalize
-object keys; depending on a `Value` map's incidental iteration order is unsafe.
-
-## Browser
-
-```sh
-npm install @corbet-labs/ccht
-```
-
-```js
-import { createConversation } from '@corbet-labs/ccht';
-// Vite example: emit the Wasm as a separately replaceable asset.
-import wasmUrl from '@corbet-labs/ccht/ccht_bg.wasm?url';
-
-const conversation = await createConversation('workspace/creator', { wasm: wasmUrl });
-// After your authenticated application transport delivers a ccht WireEvent:
-const snapshot = conversation.applyEvent(event);
-render(snapshot.turns);
-// When the view is destroyed:
-conversation.free();
-```
-
-Version 0.2.0 requires an explicit `wasm` URL or bytes on first initialization.
-A browser cannot launch native processes: its
-application server or desktop host runs `ccht::native`. The package makes no
-network connection apart from loading its Wasm module. The host decides which
-backend is available and how users authenticate to the application.
-
-## JSR
-
-The JSR package exposes the same Rust/Wasm model:
-
-```ts
-import { createConversation } from 'jsr:@corbet-labs/ccht@0.2.0';
-
-const conversation = await createConversation('workspace/creator', {
-  wasm: new URL('https://jsr.io/@corbet-labs/ccht/0.2.0/wasm/ccht_bg.wasm'),
-});
-```
-
-In Deno, allow access with `--allow-net=jsr.io` for this Wasm download.
-Applications can also supply their own Wasm bytes or URL. JSR's corresponding
-source archive uses `dependencies.tar.xz` to fit its package size limit; the
-source files and runtime bytes are the same as the npm distribution.
-
-## Python
-
-Install from [PyPI](https://pypi.org/project/ccht/0.2.0/):
-
-```sh
-python -m pip install ccht==0.2.0
-```
-
-```python
-from ccht import Conversation
-
-conversation = Conversation('workspace/creator')
-# Deliver an authorized WireEvent from your application transport.
-conversation.apply_event(event)
-snapshot = conversation.snapshot()
-```
-
-The Python package wraps the published Rust conversation model through PyO3.
-It exposes event reduction and snapshots; native agent execution uses a Rust
-host with `ccht::native`. See [py/README.md](py/README.md) for the Python API,
-binary wheel requirements and source rebuild/replacement instructions.
-
-## Event and persistence contract
-
-`WireEvent` version 1 contains `conversation_id`, `request_id`, a per-request
-`sequence` starting at 1, and `event`. Retain the original structured ACP updates:
-text, non-text content, tool calls, thought chunks, plans, permissions and errors
-are distinct. The model returns a serializable snapshot for your renderer.
-
-Assign identities and sequences on a trusted application host. Never let a browser
-select another user's conversation without server-side authorization. Sequence
-numbers are **not** SSE cursors or database row IDs. The app stores its own event
-log and replays each request in order. Already-applied sequences are ignored;
-gaps, a different conversation, malformed events and new events after completion
-fail without mutating state. Delivery identity must not be reused for another turn.
-
-A model holds at most 256 turns, 8 MiB per turn and 1 MiB per event. Applications
-should page long histories into separate models and limit streamed inputs before
-parsing them. Durable transcript storage and reconnection are application concerns;
-a serialized snapshot is a render result, not a native-agent session checkpoint.
-
-Namer is the first integration: Creator/Critic have independent conversation
-scopes, durable application events, authenticated SSE and cancellation. Its queue
-uses a fresh native session per turn with bounded role history supplied by Namer.
-CareerVector's TUI reuses the native session API while keeping CV tools, prompts
-and revision checks in its own code. Explicit local inference can emit the same
-`WireEvent` contract through an application-owned backend.
-
-## Building the Wasm package
-
-Use Rust with `wasm32-unknown-unknown` installed. The checked-in generator uses the
-same exact `wasm-bindgen` version as the Rust crate; no global Wasm CLI is required.
-
-```sh
-cargo build --locked --release --no-default-features --features web --target wasm32-unknown-unknown
-cargo run --locked --release -p ccht-wasm-bundle -- target/wasm32-unknown-unknown/release/ccht.wasm web/wasm
-```
-
-Published npm browser archives include the corresponding Rust source and generator
-under `source/`, original notices, and the full locked dependency sources in
-`source/dependencies.tar.gz`. Cargo's vendor checksums are preserved inside that
-archive. To rebuild from the distributed package, extract it inside `source/`:
-
-```sh
-cd source
-tar -xzf dependencies.tar.gz
-cargo build --locked --offline --release --no-default-features --features web --target wasm32-unknown-unknown
-cargo run --locked --offline --release -p ccht-wasm-bundle -- target/wasm32-unknown-unknown/release/ccht.wasm ../wasm
-```
-
-The supplied `.cargo/config.toml` uses only those vendored sources. The installed
-Rust toolchain must include the Wasm target and linker. CI rebuilds this kit with
-an empty Cargo cache and tests the replacement module through the same npm API.
-Keep that exported interface compatible when replacing the library.
-
-CI verifies the portable Rust model, actual Wasm compilation and packaged Node
-consumer, native protocol/process fixtures, dependency notices and an independent
-Rust crate consumer. Native fixtures do not call a model or access an account.
-Live runtime support must additionally be checked against the installed agent,
-its advertised capabilities, login state and execution policy.
-
-## License
-
-ccht is **LGPL-3.0-only**. See [LICENSE.md](LICENSE.md) and
-[THIRD-PARTY.md](THIRD-PARTY.md). Applications may use different licenses while
-preserving the LGPL library rights. Distributing a combined Rust binary requires
-a compliant relinking route; making source available somewhere is not by itself
-sufficient. Keep the browser's Wasm replaceable and provide its corresponding
-source and notices. Review the complete license for your distribution method.
-
-ACP and an account's subscription do not guarantee a billing mode. The operator
-must configure the native agent/account and disable unwanted paid usage. Known
-ambient API-key variables are cleared at launch and explicit API-key overrides
-are rejected, but ccht cannot attest saved agent credentials or account billing
-settings. Native runtimes and hosted services retain their own terms; a library
-license does not authorize pooling subscriptions or product-specific login flows.

package/source/THIRD-PARTY.md

@@ -1,45 +0,0 @@
-# Third-party components
-
-ccht uses the official `agent-client-protocol` Rust SDK and
-`agent-client-protocol-schema` under Apache-2.0. `wasm-bindgen` and the generated
-binding toolchain retain their MIT/Apache-2.0 grants. The exact locked dependency
-inventory is generated by `.ci/license_inventory.py`; browser distributions carry
-original dependency notices in `LICENSES/dependencies/`.
-No Zed editor source is included. Zed's external-agent architecture is a reference;
-its GPL editor code is not relicensed by ccht's LGPL grant.
-
-External runtimes are separately supplied by the operator:
-
-| Runtime | Source license / terms |
-| --- | --- |
-| Codex ACP adapter and Codex | Apache-2.0; OpenAI account/service terms remain applicable |
-| OpenCode | MIT; configured provider/account terms remain applicable |
-| Claude ACP adapter | Apache-2.0 wrapper; the Claude Agent SDK/runtime has separate proprietary Anthropic terms |
-
-ccht does not redistribute these executables. Preserve their original notices and
-comply with their runtime and service conditions when packaging them yourself.
-Do not infer permission to offer a customer-facing subscription login or pooled
-account service from the wrapper's permissive license.
-
-Upstream sources: [ACP SDK](https://github.com/agentclientprotocol/rust-sdk),
-[Codex ACP](https://github.com/agentclientprotocol/codex-acp),
-[Claude ACP](https://github.com/agentclientprotocol/claude-agent-acp),
-[OpenCode](https://github.com/anomalyco/opencode),
-[wasm-bindgen](https://github.com/wasm-bindgen/wasm-bindgen).
-
-The published ACP SDK and derive 2.1.0, ACP schema 1.7.0, defmt-parser 1.0.0,
-wasm-encoder 0.245.1, and wasmparser 0.245.1 archives omit their repositories'
-root license files. Their unchanged original notices are retained under
-`.ci/upstream-notices/<package>-<version>/` for inclusion in browser artifacts.
-This preserves Zed's copyright notices, both defmt license alternatives, and all
-three wasm-tools license alternatives, including the LLVM exception.
-
-The r-efi 6.0.0 archive already includes its full MIT grant, copyright notices,
-and Apache-2.0/LGPL-2.1-or-later alternative notices in `AUTHORS`. That unchanged
-file is also retained as a supplemental notice because its filename is outside
-the usual `LICENSE`/`NOTICE` convention. All these notices were verified against
-the exact upstream revisions recorded in the published crates'
-`.cargo_vcs_info.json`; their crate archive checksums match `Cargo.lock`.
-[Notice provenance](.ci/upstream-notices/PROVENANCE.json) records immutable source
-URLs, revisions, upstream paths, Git blob hashes, and SHA-256 hashes. No upstream
-implementation source or license alternatives were modified.

package/source/examples/native.rs

@@ -1,45 +0,0 @@
-//! Stream from an operator-supplied, already authenticated ACP executable.
-//!
-//! Example: cargo run --example native -- opencode acp
-
-use ccht::native::{AgentCommand, NativeClient, NativeOptions, SessionOptions};
-use ccht::{Event, Prompt, acp};
-
-#[tokio::main]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let mut arguments = std::env::args().skip(1);
-    let executable = arguments
-        .next()
-        .ok_or("supply an installed ACP executable")?;
-    let directory = std::env::current_dir()?;
-    let command = AgentCommand::new(executable)
-        .args(arguments)
-        .with_working_directory(&directory)?;
-    let client = NativeClient::connect(command, NativeOptions::default()).await?;
-    let mut session = client.new_session(SessionOptions::new(directory)).await?;
-    let handle = session.handle();
-    let mut events = session.take_events()?;
-    let reader = tokio::spawn(async move {
-        while let Some(message) = events.recv().await {
-            match message.event {
-                Event::Update {
-                    update: acp::SessionUpdate::AgentMessageChunk(chunk),
-                } => {
-                    if let acp::ContentBlock::Text(text) = chunk.content {
-                        print!("{}", text.text);
-                    }
-                }
-                Event::Completed { .. } | Event::Error { .. } => break,
-                _ => {}
-            }
-        }
-    });
-    let result = handle
-        .prompt(Prompt::text("example-turn", "Say hello in one sentence."))
-        .await;
-    client.close().await?;
-    reader.await?;
-    result?;
-    println!();
-    Ok(())
-}

package/source/src/configuration.rs

@@ -1,89 +0,0 @@
-//! Agent-owned session controls shared by native, Wasm and transport consumers.
-
-use serde::{Deserialize, Serialize};
-
-use crate::acp::{
-    SessionConfigKind, SessionConfigOption, SessionConfigOptionCategory, SessionConfigOptionValue,
-    SessionConfigSelectOptions, SessionModeState, SessionUpdate,
-};
-
-/// An agent's current advertised configuration; option order is significant.
-#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
-pub struct SessionConfiguration {
-    /// Model, mode, reasoning and other controls supplied by the agent.
-    pub options: Vec<SessionConfigOption>,
-    /// Legacy modes for agents that have not adopted configuration options.
-    pub modes: Option<SessionModeState>,
-}
-
-impl SessionConfiguration {
-    /// The first model selector, following the agent's priority ordering.
-    pub fn model_option(&self) -> Option<&SessionConfigOption> {
-        self.options.iter().find(|option| {
-            option.category == Some(SessionConfigOptionCategory::Model)
-                || option.id.0.as_ref() == "model"
-        })
-    }
-
-    /// Whether an exact value is offered, including grouped selectors and booleans.
-    pub fn accepts(&self, id: &str, value: &SessionConfigOptionValue) -> bool {
-        let Some(option) = self
-            .options
-            .iter()
-            .find(|option| option.id.0.as_ref() == id)
-        else {
-            return false;
-        };
-        match (&option.kind, value) {
-            (SessionConfigKind::Boolean(_), SessionConfigOptionValue::Boolean { .. }) => true,
-            (SessionConfigKind::Select(select), SessionConfigOptionValue::ValueId { value }) => {
-                match &select.options {
-                    SessionConfigSelectOptions::Ungrouped(options) => {
-                        options.iter().any(|option| option.value == *value)
-                    }
-                    SessionConfigSelectOptions::Grouped(groups) => groups
-                        .iter()
-                        .any(|group| group.options.iter().any(|option| option.value == *value)),
-                    _ => false,
-                }
-            }
-            _ => false,
-        }
-    }
-
-    /// Apply an agent update. Configuration updates replace the complete option list.
-    pub fn apply(&mut self, update: &SessionUpdate) {
-        match update {
-            SessionUpdate::ConfigOptionUpdate(update) => {
-                self.options.clone_from(&update.config_options);
-            }
-            SessionUpdate::CurrentModeUpdate(update) => {
-                if let Some(modes) = &mut self.modes {
-                    modes.current_mode_id.clone_from(&update.current_mode_id);
-                }
-            }
-            _ => {}
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    #[test]
-    fn grouped_selectors_and_boolean_controls_preserve_exact_types() {
-        let settings: SessionConfiguration = serde_json::from_value(serde_json::json!({
-            "options": [{"id":"model","name":"Model","category":"model","type":"select",
-                "currentValue":"one","options":[{"group":"provider","name":"Provider","options":[
-                    {"value":"one","name":"One"},{"value":"two","name":"Two"}]}]},
-                {"id":"thinking","name":"Thinking","type":"boolean","currentValue":false}],
-            "modes":null
-        }))
-        .unwrap();
-        assert!(settings.accepts("model", &"two".into()));
-        assert!(!settings.accepts("model", &true.into()));
-        assert!(settings.accepts("thinking", &true.into()));
-        assert!(!settings.accepts("thinking", &"true".into()));
-        assert!(!settings.accepts("missing", &true.into()));
-    }
-}