tau-coding-agent 0.5.0__tar.gz → 0.5.2__tar.gz

{tau_coding_agent-0.5.0/tau_coding_agent.egg-info → tau_coding_agent-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tau-coding-agent
-Version: 0.5.0
+Version: 0.5.2
 Summary: A self-extensible agent CLI with terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools and commands
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown

{tau_coding_agent-0.5.0 → tau_coding_agent-0.5.2}/docs/architecture.md

@@ -61,7 +61,7 @@ User input flows through these stages:
 | `console/` | CLI entry point, argument parsing |
 | `runtime/` | Orchestrates agent, session, engine, extensions |
 | `agent/` | Processes message turns, calls inference |
-| `engine/` | Executes tool calls and collects results |
+| `engine/` | Standalone inference and tool-execution loop |
 | `inference/` | Unified interface to LLM providers |
 
 ### Data & State
@@ -79,7 +79,7 @@ User input flows through these stages:
 
 | Module | Purpose |
 |--------|---------|
-| `tui/` | Terminal UI (22 modules) |
+| `tui/` | Standalone terminal rendering and component framework |
 | `extensions/` | Plugin system API |
 | `hooks/` | Event system for extensions |
 | `commands/` | Slash command registry |
@@ -141,6 +141,9 @@ Each agent turn follows this sequence:
 TUI overlays participate in focus lifecycle. Hiding or closing a capturing
 overlay restores the next visible overlay or its previous focus target.
 Components exposing `dispose()` are disposed when their overlay closes.
+The reusable renderer, terminal, input, and component APIs are documented in
+[Terminal UI](tui.md); runtime-aware composition lives in
+`modes/interactive/`.
 
 Slash commands declare whether they require an idle agent. Idle-only commands
 are deferred until the current turn settles; UI-only and read-only commands may
@@ -204,7 +207,9 @@ class BaseAPI:
         ...
 ```
 
-The inference module handles provider-specific details (API keys, endpoints, format conversions).
+The inference module handles provider-specific details (API keys, endpoints,
+format conversions) and can also be used independently of the agent runtime.
+See [Inference](inference.md) for its package boundaries and public clients.
 
 ## Tool Execution Model
 
@@ -223,6 +228,9 @@ Built-in tools (terminal, read, write, edit, glob, grep, ls) are enabled by defa
 `RuntimeConfig` can allow or exclude tools by name. Custom tools are registered
 via extensions or passed directly to the runtime.
 
+The engine can also be embedded without the session-aware agent or runtime.
+See [Engine](engine.md) for its public API and dependency boundary.
+
 Programmatic runtimes can replace constructed services through
 `RuntimeDependencies`. Typed factories cover settings, LLM/model/auth wiring,
 session storage, hooks, and the tool registry. Session-bound factories run

tau_coding_agent-0.5.2/docs/creating-tools.md

@@ -0,0 +1,242 @@
+# Creating Tools
+
+Tools are typed asynchronous operations that a model can request. A tool
+defines its name, description, Pydantic input schema, execution policy, and
+result handling.
+
+Use this guide to implement and test a tool. See [Tools](tools.md) for the
+built-in tool reference and execution model.
+
+## Implement a Tool
+
+This example creates a read-only word-count tool:
+
+```python
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from tau.tool.types import (
+    AbortSignal,
+    Tool,
+    ToolContext,
+    ToolExecutionMode,
+    ToolExecutionUpdateCallback,
+    ToolInvocation,
+    ToolKind,
+    ToolResult,
+)
+
+
+class WordCountParams(BaseModel):
+    """Validated parameters for the word-count tool."""
+
+    path: str = Field(description="Text file path, relative to the working directory.")
+
+
+class WordCountTool(Tool):
+    """Count words in a UTF-8 text file."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            name="word_count",
+            description="Count the words in a UTF-8 text file.",
+            schema=WordCountParams,
+            kind=ToolKind.Read,
+            execution_mode=ToolExecutionMode.Parallel,
+        )
+
+    async def execute(
+        self,
+        invocation: ToolInvocation,
+        tool_execution_update_callback: ToolExecutionUpdateCallback | None = None,
+        signal: AbortSignal | None = None,
+        context: ToolContext | None = None,
+    ) -> ToolResult:
+        params = WordCountParams.model_validate(invocation.params)
+
+        if signal is not None and signal.is_set():
+            return ToolResult.error(invocation.id, "Word count cancelled.")
+
+        base = context.cwd if context is not None and context.cwd is not None else Path.cwd()
+        path = Path(params.path)
+        if not path.is_absolute():
+            path = base / path
+
+        try:
+            content = path.read_text(encoding="utf-8")
+        except OSError as error:
+            return ToolResult.error(invocation.id, f"Cannot read {path}: {error}")
+
+        count = len(content.split())
+        return ToolResult.ok(
+            invocation.id,
+            f"{path}: {count} words",
+            metadata={"path": str(path), "word_count": count},
+        )
+```
+
+The engine validates `invocation.params` against `schema` before execution.
+Validating again inside `execute()` produces a typed parameter object and keeps
+the tool safe when called directly in tests.
+
+## Define Clear Metadata
+
+Constructor fields affect both model behavior and execution:
+
+| Field | Guidance |
+|-------|----------|
+| `name` | Use a stable lowercase identifier with underscores |
+| `description` | State what the tool does and when it should be used |
+| `schema` | Use Pydantic fields with precise descriptions and constraints |
+| `kind` | Classify the side effect as read, edit, write, execute, or web |
+| `execution_mode` | Use parallel only when concurrent calls are safe |
+
+Tools that mutate files, launch processes, or modify external state should
+normally use `ToolExecutionMode.Sequential`. Read-only operations may use
+`Parallel` when they do not share mutable state.
+
+## Return Results
+
+Return model-facing text with one of the result constructors:
+
+```python
+return ToolResult.ok(invocation.id, "Completed", metadata={"items": 3})
+return ToolResult.error(invocation.id, "The requested file does not exist")
+```
+
+Keep `content` concise and actionable. Use `metadata` for structured facts
+needed by hooks or renderers, not for duplicating the complete text result.
+
+For Markdown rendering of a successful result:
+
+```python
+return ToolResult.ok(
+    invocation.id,
+    "## Results\n\n- First\n- Second",
+    metadata={"_render_format": "markdown"},
+)
+```
+
+## Use Runtime Context
+
+`ToolContext` provides optional runtime services:
+
+| Attribute | Value |
+|-----------|-------|
+| `cwd` | Current engine working directory |
+| `llm` | Active text inference client |
+| `settings` | Active settings manager, when available |
+
+Treat every attribute as optional because tools can be unit-tested or called
+outside the complete runtime.
+
+Long-running tools should check `signal.is_set()` at safe cancellation points.
+Tools that produce incremental output can call
+`tool_execution_update_callback` with partial `ToolResult` values.
+High-frequency producers should throttle updates so they do not flood engine
+events or terminal renders. Emit an initial update when work begins and a final
+update matching the returned result.
+
+## Register the Tool
+
+### Project or Global Extension
+
+Create `.tau/extensions/word_count.py` for one project, or
+`~/.tau/extensions/word_count.py` for all projects:
+
+```python
+from tau.extensions import ExtensionAPI
+
+
+def register(tau: ExtensionAPI) -> None:
+    tau.register_tool(WordCountTool())
+```
+
+Run `/reload` after changing an extension.
+
+### Python Runtime
+
+Pass tool instances through `RuntimeConfig`:
+
+```python
+from pathlib import Path
+
+from tau.runtime.types import RuntimeConfig
+
+config = RuntimeConfig(
+    cwd=Path.cwd(),
+    tools=[WordCountTool()],
+)
+```
+
+### Standalone Engine
+
+Supply tools to both `Engine` and `EngineContext`:
+
+```python
+from pathlib import Path
+
+from tau.engine import Engine, EngineContext
+from tau.message.types import UserMessage
+
+tools = [WordCountTool()]
+engine = Engine(cwd=Path.cwd(), llm=llm, tools=tools)
+
+await engine.run(
+    EngineContext(
+        system_prompt="Use tools when they answer the request.",
+        messages=[UserMessage.from_text("Count the words in README.md")],
+        tools=tools,
+    )
+)
+```
+
+See [Engine](engine.md) for standalone lifecycle and event handling.
+
+## Test the Tool
+
+Test execution without making an inference request:
+
+```python
+from pathlib import Path
+
+import pytest
+
+from tau.tool.types import ToolContext, ToolInvocation
+
+
+@pytest.mark.asyncio
+async def test_word_count(tmp_path: Path) -> None:
+    source = tmp_path / "sample.txt"
+    source.write_text("one two three", encoding="utf-8")
+    tool = WordCountTool()
+
+    result = await tool.execute(
+        ToolInvocation(
+            id="call-1",
+            name=tool.name,
+            cwd=tmp_path,
+            params={"path": "sample.txt"},
+        ),
+        context=ToolContext(cwd=tmp_path),
+    )
+
+    assert not result.is_error
+    assert result.metadata["word_count"] == 3
+```
+
+Also test invalid parameters, missing resources, cancellation, and concurrent
+execution when the tool declares parallel safety.
+
+## Checklist
+
+- Parameter types and constraints are expressed in the Pydantic schema.
+- The description explains when the model should call the tool.
+- Side effects match `ToolKind` and `ToolExecutionMode`.
+- Errors are returned as `ToolResult.error`, not leaked as raw tracebacks.
+- Paths are resolved against `ToolContext.cwd`.
+- Cancellation is checked during long operations.
+- Unit tests cover success and failure paths.

{tau_coding_agent-0.5.0 → tau_coding_agent-0.5.2}/docs/docs.json

@@ -28,6 +28,18 @@
     {
       "title": "Core Concepts",
       "items": [
+        {
+          "title": "Inference",
+          "path": "inference.md"
+        },
+        {
+          "title": "Engine",
+          "path": "engine.md"
+        },
+        {
+          "title": "Terminal UI",
+          "path": "tui.md"
+        },
         {
           "title": "Inference Providers",
           "path": "inference-providers.md"
@@ -44,6 +56,10 @@
           "title": "Tools",
           "path": "tools.md"
         },
+        {
+          "title": "Creating Tools",
+          "path": "creating-tools.md"
+        },
         {
           "title": "Project Context",
           "path": "project-context.md"

tau_coding_agent-0.5.2/docs/engine.md

@@ -0,0 +1,114 @@
+# Engine
+
+`tau.engine` is Tau's standalone text-inference and tool-execution loop. It can
+be embedded directly when an application needs agentic model/tool iteration
+without Tau's sessions, compaction, extensions, runtime lifecycle, or terminal
+UI.
+
+Use [Inference](inference.md) instead when the application only needs a single
+model request and will manage tool calls itself. Use the
+[Python API](python-api.md) when the application needs the complete Tau runtime.
+
+## Responsibilities
+
+The engine:
+
+- streams normalized text inference events
+- accumulates assistant messages
+- validates and executes requested tools
+- runs safe tool batches sequentially or concurrently
+- emits message, turn, tool, and engine lifecycle events
+- supports steering, follow-up messages, continuation, and cancellation
+
+The engine does not persist messages, compact context, discover extensions,
+construct the application system prompt, or manage the user interface.
+`tau.agent` owns session-aware orchestration around the engine, while
+`tau.runtime` constructs and connects the full application.
+
+## Public API
+
+| Type | Purpose |
+|------|---------|
+| `Engine` | Streaming inference and tool-execution service |
+| `EngineContext` | System prompt, message history, and tools for one run |
+| `EngineOptions` | Execution strategy and lifecycle callbacks |
+| `EngineState` | Observable mutable execution state |
+
+The former `Agent` and `AgentState` names remain compatibility aliases, and
+`AgentOptions` is the descriptive compatibility name for `EngineOptions`.
+New code should use the explicit `Engine` names.
+
+## Basic Example
+
+```python
+import asyncio
+from pathlib import Path
+
+from tau.engine import Engine, EngineContext, MessageEndEvent
+from tau.inference.api.text.service import TextLLM
+from tau.message.types import UserMessage
+
+
+async def main() -> None:
+    llm = TextLLM("gpt-4o")
+    engine = Engine(cwd=Path.cwd(), llm=llm, tools=[])
+
+    def print_completed_message(event: object) -> None:
+        if isinstance(event, MessageEndEvent):
+            print(event.message)
+
+    await engine.subscribe(print_completed_message)
+    await engine.run(
+        EngineContext(
+            system_prompt="Answer concisely.",
+            messages=[UserMessage.from_text("What does an execution engine do?")],
+        )
+    )
+
+
+asyncio.run(main())
+```
+
+Configure the model provider before running the example. See
+[Inference Providers](inference-providers.md).
+
+## Supplying Tools
+
+Pass the same tool objects to both the engine and the run context:
+
+```python
+tools = [read_tool, terminal_tool]
+engine = Engine(cwd=Path.cwd(), llm=llm, tools=tools)
+
+await engine.run(
+    EngineContext(
+        system_prompt="Use tools when needed.",
+        messages=[UserMessage.from_text("Inspect this project.")],
+        tools=tools,
+    )
+)
+```
+
+Tools declare their own execution safety. A batch runs concurrently only when
+every tool in that batch permits parallel execution; otherwise source order is
+preserved.
+
+## Lifecycle Control
+
+- `subscribe(handler)` observes engine events and returns an unsubscribe
+  callback.
+- `steer(message)` injects guidance during an active tool loop.
+- `follow_up(message)` queues another user message after a natural stop.
+- `abort()` cancels the active stream at the next safe boundary.
+- `run_continue()` resumes from the engine's current in-memory history.
+- `wait_for_idle()` waits until the active loop exits.
+
+Engine history is in memory only. Applications using the engine directly are
+responsible for durable storage and for constructing the next
+`EngineContext`.
+
+## Dependency Boundary
+
+`tau.engine` depends on inference, messages, tools, hooks, and optional
+settings. It must not import session, extension, TUI, runtime, or agent
+services. This keeps the engine independently testable and embeddable.

{tau_coding_agent-0.5.0 → tau_coding_agent-0.5.2}/docs/extensions.md

@@ -130,6 +130,8 @@ async def register(tau):
 ## Tools
 
 Import from `tau.tool.types`. Use a Pydantic `BaseModel` for the parameter schema.
+For a focused walkthrough covering implementation, registration, and testing,
+see [Creating Tools](creating-tools.md).
 
 ```python
 from pydantic import BaseModel, Field
@@ -1188,7 +1190,7 @@ def my_footer(tui, theme):
     return StaticComponent([f"  {theme.primary}Custom footer{RESET}  "])
 
 # With TUI + theme + live data (recommended)
-from tau.tui.ui_context import FooterData
+from tau.modes.interactive.ui_context import FooterData
 
 def my_footer(tui, theme, data: FooterData):
     branch = data.git_branch or "detached"

{tau_coding_agent-0.5.0 → tau_coding_agent-0.5.2}/docs/index.md

@@ -23,10 +23,14 @@ Tau allows you to:
 
 ## Core Concepts
 
+- [Inference](inference.md) - Standalone inference clients, types, and architecture
+- [Engine](engine.md) - Standalone inference and tool-execution loop
+- [Terminal UI](tui.md) - Standalone terminal rendering and component framework
 - [Messages & Context](messages.md) - How messages flow and context is managed
 - [Sessions](sessions.md) - Session persistence, branching, compaction, JSONL format
 - [Inference Providers](inference-providers.md) - Supported LLMs and provider setup
 - [Tools](tools.md) - Tool registry, built-in tools, execution model
+- [Creating Tools](creating-tools.md) - Implement, register, and test custom tools
 - [Project Context Files](project-context.md) - Repository-specific agent instructions
 - [CLI Reference](cli-reference.md) - All command-line options and run modes