fix(tool): align toolkit library contract (#592)

## Summary
- align the Rust tool contract with the toolkit library spec
- update Rust docs, examples, and JS/Python wrapper metadata paths for
the new contract
- refresh wrapper tests/docs to match the new help/system prompt
surfaces

## Validation
- `cargo fmt --check`
- `cargo clippy --all-targets --all-features -- -D warnings`
- `cargo test --all-features` (fails only in `bash_comparison_tests`,
matching `origin/main` at `08d4a33` with the same 81 baseline
mismatches)
- `npm run build`
- `npm test`
- native Python wrapper check via temp venv: `maturin develop && pytest
tests/test_bashkit.py`

Author: chaliy

Cargo.toml

@@ -83,6 +83,7 @@ schemars = "1"
 
 # Logging/tracing
 tracing = "0.1"
+tower = { version = "0.5", features = ["util"] }
 
 # Serial test execution
 serial_test = "3"

README.md

@@ -53,6 +53,41 @@ async fn main() -> anyhow::Result<()> {
 }
 ```
 
+## LLM Tool Contract
+
+`BashTool` follows the toolkit-library contract: builder for reusable config,
+immutable tool metadata for discovery, and single-use executions for each call.
+
+```rust
+use bashkit::{BashTool, Tool};
+use futures::StreamExt;
+
+# #[tokio::main]
+# async fn main() -> anyhow::Result<()> {
+let tool = BashTool::builder()
+    .username("agent")
+    .hostname("sandbox")
+    .build();
+
+println!("{}", tool.description());
+println!("{}", tool.system_prompt());
+
+let execution = tool.execution(serde_json::json!({
+    "commands": "printf 'hello\nworld\n'"
+}))?;
+let mut stream = execution.output_stream().expect("stream available");
+
+let handle = tokio::spawn(async move { execution.execute().await });
+while let Some(chunk) = stream.next().await {
+    println!("{}: {}", chunk.kind, chunk.data);
+}
+
+let output = handle.await??;
+assert_eq!(output.result["stdout"], "hello\nworld\n");
+# Ok(())
+# }
+```
+
 ## Overview
 
 <div align="center">
@@ -264,6 +299,8 @@ Python bindings with LangChain integration are available in [crates/bashkit-pyth
 from bashkit import BashTool
 
 tool = BashTool()
+print(tool.description())
+print(tool.help())
 result = await tool.execute("echo 'Hello, World!'")
 print(result.stdout)
 ```

crates/bashkit-eval/src/agent.rs

@@ -77,7 +77,7 @@ pub async fn run_agent_loop(
         .build();
     let tool_def = ToolDefinition {
         name: "bash".to_string(),
-        description: tool.description(),
+        description: tool.description().to_string(),
         input_schema: tool.input_schema(),
     };
 

crates/bashkit-eval/src/scripting_agent.rs

@@ -138,11 +138,11 @@ pub async fn run_scripted_agent(
     if task.discovery_mode {
         builder = builder.with_discovery();
     }
-    let mut tool: Box<dyn Tool> = Box::new(builder.build());
+    let tool: Box<dyn Tool> = Box::new(builder.build());
 
     let tool_def = ToolDefinition {
         name: tool.name().to_string(),
-        description: tool.description(),
+        description: tool.description().to_string(),
         input_schema: tool.input_schema(),
     };
 

crates/bashkit-js/README.md

@@ -22,11 +22,13 @@ console.log(result.stdout); // Hello, World!\n
 bash.executeSync('X=42');
 bash.executeSync('echo $X'); // stdout: 42\n
 
-// With LLM tool metadata
+// With tool-contract metadata
 const tool = new BashTool();
 console.log(tool.name);           // "bashkit"
 console.log(tool.inputSchema());  // JSON schema for LLM tool-use
-console.log(tool.systemPrompt()); // System prompt for LLMs
+console.log(tool.description());  // Token-efficient tool description
+console.log(tool.help());         // Markdown help document
+console.log(tool.systemPrompt()); // Compact system prompt
 
 const r = tool.executeSync('echo hello');
 console.log(r.stdout); // hello\n
@@ -45,15 +47,15 @@ Core interpreter with virtual filesystem.
 
 ### `BashTool`
 
-Interpreter + LLM tool metadata.
+Interpreter + tool-contract metadata.
 
 - All `Bash` methods, plus:
 - `name` — tool name (`"bashkit"`)
 - `version` — version string
 - `shortDescription` — one-liner
-- `description()` — full description
-- `help()` — help text
-- `systemPrompt()` — system prompt for LLMs
+- `description()` — token-efficient tool description
+- `help()` — Markdown help document
+- `systemPrompt()` — compact system prompt for LLM orchestration
 - `inputSchema()` — JSON input schema
 - `outputSchema()` — JSON output schema
 

crates/bashkit-js/__test__/tool-metadata.spec.ts

@@ -141,6 +141,13 @@ test("BashTool: metadata unchanged after reset", (t) => {
   t.is(tool.description(), descBefore);
 });
 
+test("BashTool: systemPrompt reflects configured home path", (t) => {
+  const tool = new BashTool({ username: "agent", hostname: "sandbox" });
+  const prompt = tool.systemPrompt();
+  t.true(prompt.includes("agent"));
+  t.true(prompt.includes("/home/agent"));
+});
+
 // ============================================================================
 // BashTool — execution (basic coverage, deep tests in basic.spec.ts)
 // ============================================================================

crates/bashkit-js/src/lib.rs

@@ -136,10 +136,11 @@ impl Bash {
 }
 
 // ============================================================================
-// BashTool — interpreter + LLM tool metadata
+// BashTool — interpreter + tool-contract metadata
 // ============================================================================
 
-/// Bash interpreter with LLM tool metadata (schema, description, system_prompt).
+/// Bash interpreter with tool-contract metadata (`description`, `help`,
+/// `system_prompt`, schemas).
 ///
 /// Use this when integrating with AI frameworks that need tool definitions.
 #[napi]
@@ -152,6 +153,29 @@ pub struct BashTool {
     max_loop_iterations: Option<u32>,
 }
 
+impl BashTool {
+    fn build_rust_tool(&self) -> RustBashTool {
+        let mut builder = RustBashTool::builder();
+
+        if let Some(ref username) = self.username {
+            builder = builder.username(username);
+        }
+        if let Some(ref hostname) = self.hostname {
+            builder = builder.hostname(hostname);
+        }
+
+        let mut limits = ExecutionLimits::new();
+        if let Some(mc) = self.max_commands {
+            limits = limits.max_commands(mc as usize);
+        }
+        if let Some(mli) = self.max_loop_iterations {
+            limits = limits.max_loop_iterations(mli as usize);
+        }
+
+        builder.limits(limits).build()
+    }
+}
+
 #[napi]
 impl BashTool {
     #[napi(constructor)]
@@ -238,44 +262,39 @@ impl BashTool {
     /// Get short description.
     #[napi(getter)]
     pub fn short_description(&self) -> &str {
-        "Virtual bash interpreter with virtual filesystem"
+        "Run bash commands in an isolated virtual filesystem"
     }
 
-    /// Get full description.
+    /// Get token-efficient tool description.
     #[napi]
     pub fn description(&self) -> String {
-        let tool = RustBashTool::default();
-        tool.description()
+        self.build_rust_tool().description().to_string()
     }
 
-    /// Get help text.
+    /// Get help as a Markdown document.
     #[napi]
     pub fn help(&self) -> String {
-        let tool = RustBashTool::default();
-        tool.help()
+        self.build_rust_tool().help()
     }
 
-    /// Get system prompt for LLMs.
+    /// Get compact system-prompt text for orchestration.
     #[napi]
     pub fn system_prompt(&self) -> String {
-        let tool = RustBashTool::default();
-        tool.system_prompt()
+        self.build_rust_tool().system_prompt()
     }
 
     /// Get JSON input schema as string.
     #[napi]
     pub fn input_schema(&self) -> napi::Result<String> {
-        let tool = RustBashTool::default();
-        let schema = tool.input_schema();
+        let schema = self.build_rust_tool().input_schema();
         serde_json::to_string_pretty(&schema)
             .map_err(|e| napi::Error::from_reason(format!("Schema serialization failed: {e}")))
     }
 
     /// Get JSON output schema as string.
     #[napi]
     pub fn output_schema(&self) -> napi::Result<String> {
-        let tool = RustBashTool::default();
-        let schema = tool.output_schema();
+        let schema = self.build_rust_tool().output_schema();
         serde_json::to_string_pretty(&schema)
             .map_err(|e| napi::Error::from_reason(format!("Schema serialization failed: {e}")))
     }

crates/bashkit-js/wrapper.ts

@@ -83,7 +83,7 @@ export class Bash {
 }
 
 /**
- * Bash interpreter with LLM tool metadata (schema, description, system_prompt).
+ * Bash interpreter with tool-contract metadata.
  *
  * Use this when integrating with AI frameworks that need tool definitions.
  *
@@ -94,6 +94,7 @@ export class Bash {
  * const tool = new BashTool();
  * console.log(tool.name);           // "bashkit"
  * console.log(tool.inputSchema());  // JSON schema string
+ * console.log(tool.help());         // Markdown help document
  *
  * const result = tool.executeSync('echo hello');
  * console.log(result.stdout);       // hello\n
@@ -141,17 +142,17 @@ export class BashTool {
     return this.native.shortDescription;
   }
 
-  /** Full description. */
+  /** Token-efficient tool description. */
   description(): string {
     return this.native.description();
   }
 
-  /** Help text. */
+  /** Markdown help document. */
   help(): string {
     return this.native.help();
   }
 
-  /** System prompt for LLMs. */
+  /** Compact system prompt for orchestration. */
   systemPrompt(): string {
     return this.native.systemPrompt();
   }

crates/bashkit-python/README.md

@@ -80,14 +80,16 @@ bash = Bash(
 
 ### BashTool — Convenience Wrapper for AI Agents
 
-`BashTool` is a convenience wrapper specifically designed for AI agents. It wraps `Bash` and adds LLM tool metadata (schema, description, system prompt) needed by tool-use protocols. Use this when integrating with LangChain, PydanticAI, or similar agent frameworks.
+`BashTool` is a convenience wrapper specifically designed for AI agents. It wraps `Bash` and adds contract metadata (`description`, Markdown `help`, `system_prompt`, JSON schemas) needed by tool-use protocols. Use this when integrating with LangChain, PydanticAI, or similar agent frameworks.
 
 ```python
 from bashkit import BashTool
 
 tool = BashTool()
 print(tool.input_schema())    # JSON schema for LLM tool-use
+print(tool.description())     # Token-efficient tool description
 print(tool.system_prompt())   # Token-efficient prompt
+print(tool.help())            # Markdown help document
 
 result = await tool.execute("echo 'Hello!'")
 ```
@@ -156,16 +158,16 @@ print(result.stdout)  # Alice
 - `execute(commands: str) -> ExecResult` — execute commands asynchronously
 - `execute_sync(commands: str) -> ExecResult` — execute commands synchronously
 - `reset()` — reset interpreter state
-- `description() -> str` — tool description for LLM integration
-- `help() -> str` — detailed documentation
-- `input_schema() -> str` — JSON input schema
-- `output_schema() -> str` — JSON output schema
 
 ### BashTool
 
 Convenience wrapper for AI agents. Inherits all execution methods from `Bash`, plus:
 
+- `description() -> str` — token-efficient tool description
+- `help() -> str` — Markdown help document
 - `system_prompt() -> str` — token-efficient system prompt for LLM integration
+- `input_schema() -> str` — JSON input schema
+- `output_schema() -> str` — JSON output schema
 
 ### ExecResult