Merge pull request #31 from Sewer56/split/task-tool-core-only

Split task-tool: extract core module refactor + docs

Author: Sewer56

src/Cargo.lock

@@ -10,9 +10,9 @@ readme = "README.md"
 
 [features]
 default = ["tokio"]
-# Base async signatures - requires a runtime, do not enable directly
-async = ["dep:async-trait"]
-# Async with tokio runtime (default)
+# Base async support (enabled by runtimes like tokio). PRs for other runtimes (smol, async-std) are welcome!
+async = []
+# Async with tokio runtime (default). Enables async feature and tokio-specific implementations.
 tokio = ["async", "dep:tokio", "dep:reqwest", "process-wrap/tokio1", "process-wrap/job-object", "process-wrap/process-group", "process-wrap/kill-on-drop"]
 # Blocking/sync mode - mutually exclusive with async
 blocking = ["maybe-async/is_sync", "dep:reqwest", "reqwest?/blocking", "process-wrap/std", "process-wrap/job-object", "process-wrap/process-group"]
@@ -48,9 +48,6 @@ reqwest = { version = "0.13", default-features = false, features = [
 # Unifies async/sync code via procedural macros
 maybe-async = "0.2"
 
-# TaskExecutor trait requires async methods
-async-trait = { version = "0.1", optional = true }
-
 # Async file I/O, process execution, and timeouts
 tokio = { version = "1.49", features = ["fs", "io-util", "process", "time"], optional = true }
 
@@ -62,3 +59,4 @@ tempfile = "3.24"
 # For async tests (when async feature enabled)
 tokio = { version = "1.49", features = ["rt", "macros"] }
 wiremock = "0.6"
+indoc = "2"

src/llm-coding-tools-core/Cargo.toml

@@ -1,64 +1,240 @@
 # llm-coding-tools-core
 
-Lightweight, high-performance core types and utilities for coding tools - framework agnostic.
+Framework-agnostic core library of standard tools used by coding agents - headless, TUI, or anything in between.
 
-## Overview
+`llm-coding-tools-core` provides reviewed, production-grade implementations of common coding-agent tools, plus shared safety, prompt, and policy primitives.
 
-This crate provides the foundational building blocks for coding tool implementations:
+## Table of contents
 
-- `ToolError` - Unified error type for all tool operations
-- `ToolResult<T>` - Result type alias using ToolError
-- `ToolOutput` - Wrapper for tool responses with truncation metadata
-- Utility functions for text processing and formatting
-- `context` module - LLM guidance strings for tool usage
+- [Install](#install)
+- [Feature flags](#feature-flags)
+- [Tools, context, and integration](#tools-context-and-integration)
+- [System prompt builder](#system-prompt-builder)
+- [Permissions](#permissions)
 
-## Features
+## Install
 
-- `tokio` (default): Async mode with tokio runtime. Enables async function signatures.
-- `blocking`: Sync/blocking mode. Mutually exclusive with `tokio`/`async`.
-- `async`: Base async signatures (internal). Requires a runtime; use `tokio` instead.
+```toml
+# Async (default)
+llm-coding-tools-core = "0.2"
 
-The `async` and `blocking` features are mutually exclusive - enabling both causes a compile error.
+# Sync/blocking
+llm-coding-tools-core = { version = "0.2", default-features = false, features = ["blocking"] }
+```
 
-Future runtimes (smol, async-std) can be added following the same pattern as `tokio`.
+## Feature flags
 
-## Usage
+- `tokio` (default): async runtime support
+- `blocking`: sync/blocking mode
+- `async`: internal base async feature (enabled by runtimes, not directly)
 
-```rust
-use llm_coding_tools_core::{ToolError, ToolResult, ToolOutput};
-use llm_coding_tools_core::util::{truncate_text, format_numbered_line};
+`tokio` and `blocking` are mutually exclusive.
+
+## Tools, context, and integration
+
+Canonical tool names are defined in [`tool_names`] ([`Read`], [`Write`], [`Edit`], [`Glob`], [`Grep`], [`Bash`], [`WebFetch`], [`TodoRead`], [`TodoWrite`], [`Task`]).
+
+### Standard tools
+
+- [`Read`] ([`read_file`]) - Read a file window (`offset`/`limit`) with const-generic line numbers (`read_file::<_, true>` or `read_file::<_, false>`).
+- [`Write`] ([`write_file`]) - Create or overwrite a file at a resolved path.
+- [`Edit`] ([`edit_file`]) - Apply exact text replacements with structured edit errors.
+- [`Glob`] ([`glob_files`]) - Match filesystem paths by glob pattern.
+- [`Grep`] ([`grep_search`]) - Search file contents by regex with match metadata.
+- [`Bash`] ([`execute_command`]) - Execute shell commands with timeout and captured output.
+- [`WebFetch`] ([`fetch_url`]) - Fetch URL content as text, markdown, or html (requires `tokio` or `blocking`).
+- [`TodoRead`] ([`read_todos`]) - Read shared todo state.
+- [`TodoWrite`] ([`write_todos`]) - Write and validate shared todo state.
+- [`Task`] ([`TaskInput`], [`TaskOutput`]) - Standard task payload types used by delegation wrappers.
+
+### Path safety and sandboxing
+
+Path-based tools are generic over [`PathResolver`], so wrappers can choose unrestricted access or sandboxed access.
+
+- [`AbsolutePathResolver`] enforces absolute-path inputs (unrestricted mode).
+- [`AllowedPathResolver`] constrains operations to configured directories (sandbox mode).
+- Failed resolution rejects traversal and out-of-sandbox paths before tool execution.
+
+```rust,no_run
+use llm_coding_tools_core::{AbsolutePathResolver, AllowedPathResolver, PathResolver, ToolResult};
+
+fn demo() -> ToolResult<()> {
+    // Unrestricted mode: any absolute path is allowed.
+    let any_path = AbsolutePathResolver;
+    let _hosts = any_path.resolve("/etc/hosts")?;
+
+    // Sandboxed mode: only configured directories are allowed.
+    let sandbox = AllowedPathResolver::new(["/workspace/project", "/tmp"])?;
+    let _lib = sandbox.resolve("src/lib.rs")?;
+    Ok(())
+}
 ```
 
-## Context Module
+### Context and wrapper mapping
 
-The `context` module provides embedded strings containing usage guidance for LLM agents.
-These can be appended to tool descriptions or system prompts.
+[`context`] provides reusable guidance constants.
 
-Path-based tools have two variants:
-- `*_ABSOLUTE`: For unrestricted filesystem access (absolute paths required)
-- `*_ALLOWED`: For sandboxed access (paths relative to allowed directories)
+Wrappers usually bind a tool's canonical name and guidance through [`ToolContext`]:
 
-```rust
-use llm_coding_tools_core::context::{BASH, READ_ABSOLUTE, READ_ALLOWED};
+Any-path read tool:
+
+```rust,no_run
+use llm_coding_tools_core::{ToolContext, context, tool_names};
+
+struct ReadTool;
 
-// Non-path tools have a single variant
-println!("{}", BASH);
+impl ReadTool {
+    fn new() -> Self {
+        Self
+    }
+}
 
-// Path-based tools have absolute and allowed variants
-println!("{}", READ_ABSOLUTE);
-println!("{}", READ_ALLOWED);
+impl ToolContext for ReadTool {
+    const NAME: &'static str = tool_names::READ;
+
+    fn context(&self) -> &'static str {
+        context::READ_ABSOLUTE
+    }
+}
+
+let _tool = ReadTool::new();
 ```
 
-Available context strings:
-- `BASH`, `TASK`, `TODO_READ`, `TODO_WRITE`, `WEBFETCH` - standalone tools
-- `READ_ABSOLUTE`, `READ_ALLOWED` - file reading
-- `WRITE_ABSOLUTE`, `WRITE_ALLOWED` - file writing
-- `EDIT_ABSOLUTE`, `EDIT_ALLOWED` - file editing
-- `GLOB_ABSOLUTE`, `GLOB_ALLOWED` - pattern matching
-- `GREP_ABSOLUTE`, `GREP_ALLOWED` - content search
+Sandboxed read tool:
+
+```rust,no_run
+use llm_coding_tools_core::{AllowedPathResolver, ToolContext, context, tool_names};
+
+struct ReadTool {
+    _resolver: AllowedPathResolver,
+}
+
+impl ReadTool {
+    fn new(resolver: AllowedPathResolver) -> Self {
+        Self {
+            _resolver: resolver,
+        }
+    }
+}
+
+impl ToolContext for ReadTool {
+    const NAME: &'static str = tool_names::READ;
+
+    fn context(&self) -> &'static str {
+        context::READ_ALLOWED
+    }
+}
+
+let resolver = AllowedPathResolver::new(["/workspace/project"]).expect("valid allowed path");
+let _tool = ReadTool::new(resolver);
+```
 
-## Design Principles
+Core tool functions are generic over [`PathResolver`], but wrappers usually expose separate absolute/allowed tool types for simpler ergonomics (to avoid extra generic parameters).
+
+This keeps registration name (`Read`) and prompt guidance in sync.
+
+## System prompt builder
+
+[`SystemPromptBuilder`] builds one prompt string for agent runtimes.
+
+- [`track(&mut self, tool: T)`] records tool guidance and returns the tool unchanged.
+- [`working_directory(self, path)`] and [`allowed_paths(self, resolver)`] add environment metadata.
+- [`add_context(self, name, context)`] appends supplemental sections (for example `GIT_WORKFLOW`).
+- [`system_prompt(self, prompt)`] prepends custom instructions; [`build(self)`] renders the final prompt.
+
+You usually build framework wrappers from these primitives (`ToolContext` + `SystemPromptBuilder`).
+
+### Typical wrapper integration (serdesAI)
+
+For example with `llm-coding-tools-serdesai`, wrappers are built from these primitives.
+
+```rust,no_run
+# #[cfg(any())]
+# {
+use llm_coding_tools_serdesai::absolute::{GlobTool, GrepTool, ReadTool};
+use llm_coding_tools_serdesai::{BashTool, SystemPromptBuilder};
+use serdes_ai::prelude::*;
+
+let mut pb = SystemPromptBuilder::new()
+    .working_directory(std::env::current_dir()?.display().to_string());
+
+let agent = AgentBuilder::<(), String>::new(model)
+    .tool(pb.track(ReadTool::<true>::new()))
+    .tool(pb.track(GlobTool::new()))
+    .tool(pb.track(GrepTool::<true>::new()))
+    .tool(pb.track(BashTool::new()))
+    .system_prompt(pb.build())
+    .build();
+# }
+```
+
+## Permissions
+
+[`permissions`] provides ordered allow/deny rules for tool access and delegation.
+
+- [`Rule`] stores `(permission_key, subject_pattern, action)`.
+- [`Ruleset`] uses last-match-wins; no match defaults to [`PermissionAction::Deny`].
+- Permission keys are exact-match; wildcard matching (`*`, `?`) applies to subject patterns.
+
+Frontmatter-style config is typically translated into this model:
+
+```yaml
+permission:
+  bash: allow
+  task:
+    orchestrator-*: allow
+    "*": deny
+```
+
+With last-match-wins, the final `"*": deny` rule overrides earlier `task` matches.
+
+```rust
+use llm_coding_tools_core::permissions::{PermissionAction, Rule, Ruleset};
+
+let mut rules = Ruleset::new();
+rules.push(Rule::new("bash", "*", PermissionAction::Allow));
+rules.push(Rule::new("task", "orchestrator-*", PermissionAction::Allow));
+rules.push(Rule::new("task", "*", PermissionAction::Deny));
+
+assert_eq!(rules.evaluate("bash", "any-agent"), PermissionAction::Allow);
+assert_eq!(rules.evaluate("task", "orchestrator-review"), PermissionAction::Deny); // last-match-wins
+```
 
-- No framework-specific dependencies, plug and play into any LLM framework/library
-- Minimal dependency footprint
-- Performance-oriented (optimized) with zero-cost abstractions
+[`tool_names`]: crate::tool_names
+[`Read`]: crate::tool_names::READ
+[`Write`]: crate::tool_names::WRITE
+[`Edit`]: crate::tool_names::EDIT
+[`Glob`]: crate::tool_names::GLOB
+[`Grep`]: crate::tool_names::GREP
+[`Bash`]: crate::tool_names::BASH
+[`WebFetch`]: crate::tool_names::WEBFETCH
+[`TodoRead`]: crate::tool_names::TODO_READ
+[`TodoWrite`]: crate::tool_names::TODO_WRITE
+[`Task`]: crate::tool_names::TASK
+[`read_file`]: crate::read_file
+[`write_file`]: crate::write_file
+[`edit_file`]: crate::edit_file
+[`glob_files`]: crate::glob_files
+[`grep_search`]: crate::grep_search
+[`execute_command`]: crate::execute_command
+[`fetch_url`]: crate::fetch_url
+[`read_todos`]: crate::read_todos
+[`write_todos`]: crate::write_todos
+[`TaskInput`]: crate::TaskInput
+[`TaskOutput`]: crate::TaskOutput
+[`SystemPromptBuilder`]: crate::SystemPromptBuilder
+[`track(&mut self, tool: T)`]: crate::SystemPromptBuilder::track
+[`working_directory(self, path)`]: crate::SystemPromptBuilder::working_directory
+[`allowed_paths(self, resolver)`]: crate::SystemPromptBuilder::allowed_paths
+[`add_context(self, name, context)`]: crate::SystemPromptBuilder::add_context
+[`system_prompt(self, prompt)`]: crate::SystemPromptBuilder::system_prompt
+[`build(self)`]: crate::SystemPromptBuilder::build
+[`context`]: crate::context
+[`ToolContext`]: crate::context::ToolContext
+[`PathResolver`]: crate::PathResolver
+[`AbsolutePathResolver`]: crate::AbsolutePathResolver
+[`AllowedPathResolver`]: crate::AllowedPathResolver
+[`permissions`]: crate::permissions
+[`Rule`]: crate::permissions::Rule
+[`Ruleset`]: crate::permissions::Ruleset
+[`PermissionAction::Deny`]: crate::permissions::PermissionAction::Deny

src/llm-coding-tools-core/README.md

@@ -55,7 +55,7 @@ fn main() {
 }
 
 // Mock tools implementing ToolContext for demonstration.
-// In real usage, these would be actual tool structs from a framework integration.
+// In real usage, these would be actual tool structs from llm-coding-tools-serdesai.
 
 struct MockReadTool;
 impl ToolContext for MockReadTool {

src/llm-coding-tools-core/examples/system_prompt_preview.rs

@@ -79,7 +79,7 @@ pub const GREP_ALLOWED: &str = include_str!("grep_allowed.txt");
 
 /// Trait for tools that provide usage context for LLM system prompts.
 ///
-/// Implement this trait on tool types to enable automatic system prompt
+/// Implement this trait on tool types (for frameworks like serdesAI) to enable automatic system prompt
 /// generation via [`SystemPromptBuilder`](crate::SystemPromptBuilder).
 ///
 /// # Example