tau-coding-agent 0.4.5__tar.gz → 0.4.7__tar.gz

{tau_coding_agent-0.4.5/tau_coding_agent.egg-info → tau_coding_agent-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tau-coding-agent
-Version: 0.4.5
+Version: 0.4.7
 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
@@ -26,6 +26,7 @@ Requires-Dist: pygments==2.20.0
 Requires-Dist: pathspec==1.1.1
 Requires-Dist: gitpython==3.1.50
 Requires-Dist: grapheme==0.6.0
+Requires-Dist: arrow==1.4.0
 Provides-Extra: tools
 Requires-Dist: ripgrep>=14.0.0; extra == "tools"
 Dynamic: license-file

{tau_coding_agent-0.4.5 → tau_coding_agent-0.4.7}/docs/architecture.md

@@ -70,6 +70,7 @@ User input flows through these stages:
 |--------|---------|
 | `session/` | Session JSONL persistence, compaction, branching |
 | `settings/` | Configuration from JSON files |
+| `resources/` | Unified discovery of extensions, skills, prompts, and themes |
 | `auth/` | Credential storage and resolution |
 | `message/` | Message type definitions |
 | `trust/` | Trust and permission checks |
@@ -97,7 +98,7 @@ User input flows through these stages:
 
 | Module | Purpose |
 |--------|---------|
-| `packages/` | Package/dependency management (reserved) |
+| `packages/` | Installed package and dependency management |
 | `rpc/` | JSON-RPC protocol for IDE integration |
 
 ## Agent Execution State Machine
@@ -141,6 +142,11 @@ 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.
 
+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
+opt into immediate dispatch during a turn. Normal Enter input remains steering,
+and Alt+Enter remains a post-turn follow-up message.
+
 ## Message Types and Context
 
 Messages in sessions are typed:
@@ -211,12 +217,37 @@ Tools are executed in a sandboxed environment:
 6. Result is serialized and added to context
 ```
 
-Built-in tools (bash, read, write, edit, glob, grep, ls) are always available. Custom tools are registered via extensions.
+Built-in tools (bash, read, write, edit, glob, grep, ls) are enabled by default.
+`RuntimeConfig` can allow or exclude tools by name. Custom tools are registered
+via extensions or passed directly to the runtime.
+
+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
+again when the active session is replaced.
+
+`Runtime.create_with_result()` returns the initialized runtime together with
+resource diagnostics, extension errors, and requested-versus-selected
+model/provider resolution. `Runtime.create()` remains the convenience API when
+the caller does not need startup details.
+
+Extension reloads pass through a serialized coordinator. Callback-triggered or
+mid-turn requests wait until extension dispatch and the agent lifecycle settle.
+Runtime generations invalidate contexts captured before reload, session
+replacement, or shutdown, and shutdown detaches the extension runtime from its
+hook bus.
 
 ## Extension Points
 
 Tau is designed to be extended without modifying core code. Key extension points via the `tau` parameter in `register()`:
 
+Resource discovery is centralized behind the replaceable `ResourceLoader`
+protocol. `DefaultResourceLoader` supports per-resource overrides. Startup and
+`/reload` consume one `ResourceSnapshot`, keeping extensions, skills, prompts,
+themes, context files, and structured diagnostics consistent. Diagnostics
+identify invalid configured paths, package manifests/resources, hook paths, and
+context read failures without preventing valid resources from loading.
+
 ### Tools
 
 Register custom tools that the agent can call:

{tau_coding_agent-0.4.5 → tau_coding_agent-0.4.7}/docs/cli-reference.md

@@ -31,6 +31,13 @@ augment it.
 
 ## Run Modes
 
+## Interactive Commands
+
+`/watch <url> [question]` loads metadata and available English captions for a
+public video through `yt-dlp`, then sends them to the active model. Install
+`yt-dlp` separately and ensure it is available on `PATH`. Video frames and
+audio transcription are not performed.
+
 ### Interactive (default)
 
 Start the full terminal UI:

{tau_coding_agent-0.4.5 → tau_coding_agent-0.4.7}/docs/docs.json

@@ -43,6 +43,10 @@
         {
           "title": "Tools",
           "path": "tools.md"
+        },
+        {
+          "title": "Project Context",
+          "path": "project-context.md"
         }
       ]
     },

{tau_coding_agent-0.4.5 → tau_coding_agent-0.4.7}/docs/extensions.md

@@ -89,6 +89,34 @@ def register(tau):
     pass
 ```
 
+### Inline extension factories
+
+Python API users can supply the same registration function directly through
+`RuntimeConfig`, without creating or installing an extension file:
+
+```python
+from tau.extensions import ExtensionAPI
+from tau.runtime.types import RuntimeConfig
+
+def configure(tau: ExtensionAPI) -> None:
+    tau.register_tool(MyTool())
+    tau.append_prompt("Use the embedding application's workflow.")
+
+config = RuntimeConfig(
+    cwd=Path.cwd(),
+    extension_factories=[configure],
+)
+```
+
+Inline factories receive the normal `ExtensionAPI`, can be synchronous or
+asynchronous, and load after file-based extensions. They participate in the
+same tool, command, hook, provider, service, prompt, theme, and UI registration
+systems. Factory failures are isolated and reported as `ExtensionError`.
+
+`/reload` unloads the old inline extensions and executes the factories again,
+preventing duplicate hook subscriptions. Session replacement reuses the active
+extension runtime and does not rerun factories.
+
 `register` may be `async` if setup requires awaiting:
 
 ```python
@@ -459,6 +487,34 @@ def register(tau):
 | `input` | `text`, `source` | `InputEventResult` | New user message received. `source`: `interactive \| rpc \| extension \| queue`. Return `action="transform"` with `text=` to replace, or `action="handled"` to suppress |
 | `context` | `messages` | `ContextEventResult` | Full message history about to be sent to LLM. Return `messages=` to rewrite it |
 
+For dynamic browser or computer-use state that must be refreshed before every
+LLM request without being persisted, return `ephemeral_messages` from a
+`context` handler:
+
+```python
+from tau.hooks import ContextEventResult
+from tau.message.types import UserMessage
+
+def register(tau):
+    @tau.on("context")
+    async def inject_state(event, ctx):
+        screenshot = await capture_screen()
+        return ContextEventResult(
+            ephemeral_messages=[
+                UserMessage.with_images(
+                    "Current browser state",
+                    images=[screenshot],
+                )
+            ]
+        )
+```
+
+The hook runs before every inference, including after tool execution.
+`ephemeral_messages` must contain only `UserMessage` objects. They are appended
+only to the provider request, are not persisted, and are excluded from
+Anthropic prompt-cache breakpoints. Use `messages=` in the same result to
+replace the stable request context.
+
 **Streaming & messages**
 
 | Event | Payload fields | Result type | Description |
@@ -786,7 +842,7 @@ def register(tau):
 | Method | Description |
 |--------|-------------|
 | `tau.register_tool(tool)` | Add a tool the agent can call |
-| `tau.register_command(name, desc, handler, aliases=[], get_argument_completions=None)` | Add a `/name` slash command with optional argument tab-completion |
+| `tau.register_command(name, desc, handler, aliases=[], get_argument_completions=None, argument_hint=None, requires_idle=True)` | Add a `/name` slash command; set `requires_idle=False` only for UI-only or read-only handlers safe during an active turn |
 | `tau.on(event, handler)` / `@tau.on(event)` | Subscribe to a lifecycle event |
 | `tau.register_shortcut(key, desc, handler)` | Bind a keyboard shortcut |
 | `tau.append_prompt(text)` | Append text to the system prompt |
@@ -1423,6 +1479,18 @@ async def on_start(event, ctx):
 `/reload` re-discovers and hot-reloads all extensions, skills, prompts, and
 settings without restarting the session.
 
+Reload requests are serialized. A request made from an extension callback or
+while the agent is processing is queued until the callback pipeline and complete
+agent lifecycle settle. Multiple queued requests are coalesced. Consequently,
+`await ctx.reload()` acknowledges a request but does not guarantee that a
+deferred reload has already completed.
+
+Contexts are generation-bound. An `ExtensionContext` captured before `/reload`,
+`/new`, `/resume`, `/clone`, or runtime shutdown raises
+`StaleExtensionContextError` when reused. Do not retain contexts in long-lived
+background tasks; capture immutable values or acquire a fresh context from a
+new callback.
+
 **What gets picked up:**
 - New or modified extension files
 - New or modified skill and prompt template files
@@ -1432,10 +1500,16 @@ settings without restarting the session.
 **What persists across reload:**
 - The current session (messages, branching state)
 - Auth credentials
-- Any runtime state your extension stored outside its module (e.g. in a global variable — module globals are re-created on reload)
+- Normally imported third-party Python modules, which remain cached in `sys.modules`
+- External state not explicitly released by the extension
 
 **What resets:**
 - All registered tools, commands, shortcuts, and event handlers — re-registered from scratch
 - The system prompt — rebuilt from SYSTEM.md and all `append_prompt` calls
+- Extension entry-module globals and inline factory state
+
+Tau emits `extension_unload` before replacing an extension runtime and
+`runtime_stop` before shutdown. Use those events to release subprocesses,
+background tasks, sockets, and registrations outside Tau.
 
 After reload, new tools are available to the model immediately in the next turn.

{tau_coding_agent-0.4.5 → tau_coding_agent-0.4.7}/docs/index.md

@@ -27,6 +27,7 @@ Tau allows you to:
 - [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
+- [Project Context Files](project-context.md) - Repository-specific agent instructions
 - [CLI Reference](cli-reference.md) - All command-line options and run modes
 
 ## Configuration & Customization

{tau_coding_agent-0.4.5 → tau_coding_agent-0.4.7}/docs/messages.md

@@ -62,9 +62,14 @@ Output from executing a tool.
 }
 ```
 
+Assistant text and thinking content are rendered as Markdown in the interactive
+TUI, including while content is streaming. Tool results remain plain text unless
+the tool explicitly marks a successful result for Markdown rendering.
+
 ### System Message
 
-Context and instructions for the agent. Loaded from `.agents.md` file in project or home directory.
+Context and instructions for the agent. Tau constructs this separately from
+persisted session messages and may include trusted project context files.
 
 ```python
 {
@@ -145,17 +150,18 @@ Use `@` in the editor to fuzzy-search files.
 
 ## System Instructions
 
-Tau loads system instructions from `.agents.md` files in your project or home directory:
+Tau loads project instructions from context files:
+
+**Within a Git repository:**
 
-**Project-level** (priority):
-- `.agents.md` or `agents.md` in project root or parent directories
-- Injected into context for the current project
+- `AGENTS.md` or `CLAUDE.md`, matched case-insensitively
+- One file per directory from the repository root through the current directory
+- Files closer to the current directory take precedence
 
-**Global**:
-- `~/.tau/agents.md` in home directory
-- Used as fallback for all projects
+Outside a Git repository, only the current directory is checked. Context files
+are loaded only for trusted projects.
 
-Example `.agents.md`:
+Example `AGENTS.md`:
 
 ```markdown
 # Project Instructions
@@ -167,6 +173,7 @@ Example `.agents.md`:
 ```
 
 Instructions are automatically injected into every turn sent to the LLM.
+See [Project Context Files](project-context.md) for complete behavior.
 
 ## Message Delivery
 

{tau_coding_agent-0.4.5 → tau_coding_agent-0.4.7}/docs/project-context.md

@@ -5,9 +5,13 @@ Tau automatically discovers and includes project-specific instructions from `AGE
 ## Overview
 
 When you run Tau in a project directory, it:
+
 1. Looks for `AGENTS.md` or `CLAUDE.md` (case-insensitive)
-2. If found and the project is trusted, includes the content in the system prompt
-3. Prioritizes project instructions above general Tau guidelines
+2. Walks from the Git repository root through the current directory
+3. If the project is trusted, includes one context file from each directory
+4. Prioritizes the closest file above parent files, general Tau rules, and tool guidelines
+
+Outside a Git repository, Tau checks only the current directory.
 
 This is useful for:
 - **Coding standards** — Define how the agent should write code
@@ -53,13 +57,14 @@ Or use `CLAUDE.md` for the same purpose (they're equivalent).
 
 ### File priority
 
-Tau checks for these files in order (case-insensitive):
+Tau checks for these names case-insensitively, in this order:
+
 1. `AGENTS.md`
-2. `AGENTS.MD`
-3. `CLAUDE.md`
-4. `CLAUDE.MD`
+2. `CLAUDE.md`
 
-The first one found is used.
+The first one found in each directory is used. When multiple directories provide
+instructions, Tau orders them from the repository root to the current directory.
+The closest file takes precedence if instructions conflict.
 
 ## Trust & Security
 
@@ -140,7 +145,8 @@ Project-specific guidelines and rules (from AGENTS.md):
 
 [Content of AGENTS.md here]
 
-Follow project-specific instructions before general Tau guidelines.
+Files are ordered from the repository root toward the current directory; later
+files take precedence.
 ```
 
 The agent sees this and prioritizes project instructions when making decisions.
@@ -220,14 +226,15 @@ The agent sees this and prioritizes project instructions when making decisions.
 ## Common Issues
 
 **Project context not appearing**
-- Check the file exists in the project root
-- Verify filename is exactly `AGENTS.md` or `CLAUDE.md`
+
+- Check the file exists between the repository root and current directory
+- Verify the filename is `AGENTS.md` or `CLAUDE.md`, in any letter case
 - Check project trust: `tau --approve` or `/trust` command
 - Use `--no-context-files` to confirm it's being loaded
 
 **Want to see if it's loaded**
-- Run with `--verbose` flag for logging (when available)
-- Check system prompt in `/session` command
+
+- Inspect the effective system prompt through the Python API or an extension context
 
 **Trust decisions not persisting**
 - By default, trust decisions are stored in `~/.tau/trust.json`
@@ -239,7 +246,7 @@ The agent sees this and prioritizes project instructions when making decisions.
 | Approach | When to use | Pros | Cons |
 |----------|-----------|------|------|
 | **AGENTS.md/CLAUDE.md** | Team project guidelines | Lightweight, auto-discovered, version-controlled | Limited to per-project |
-| **Custom prompt (`--system-prompt`)** | One-off instructions | Flexible | Lost after session |
+| **Custom prompt (`--system`)** | Complete one-off prompt replacement | Flexible | Bypasses generated tools, project context, skills, Git, environment, and append sections |
 | **settings.json** | User/global preferences | Persistent | Not project-specific |
 | **Environment variables** | Sensitive data, deployment-specific | Secure, flexible | Not human-readable |
 

{tau_coding_agent-0.4.5 → tau_coding_agent-0.4.7}/docs/project-structure.md

@@ -1,11 +1,11 @@
 # Project Structure
 
-Tau consists of 205 Python modules organized into 22 main packages. This page documents the codebase organization and provides module-by-module reference for contributors and agents.
+Tau consists of 230 Python modules organized into 25 main packages. This page documents the codebase organization and provides module-by-module reference for contributors and agents.
 
 ## Directory Structure
 
 ```
-tau/                                # Main package (205 modules)
+tau/                                # Main package (230 modules)
 ├── __init__.py
 ├── content_registry.py             # Content registry abstractions
 ├── agent/                          # Agent execution service
@@ -31,6 +31,7 @@ tau/                                # Main package (205 modules)
 ├── message/                        # Message types and utilities
 ├── packages/                       # Package/dependency management
 ├── prompts/                        # Prompt template system
+├── resources/                      # Unified runtime resource discovery
 ├── rpc/                            # JSON-RPC protocol for IDE integration
 ├── runtime/                        # Agent runtime service
 ├── session/                        # Session management and persistence
@@ -154,12 +155,22 @@ Message data structures and utilities.
 
 ### `packages/` - Package Management
 
-Package/dependency resolution (reserved for future use).
+Installed package and dependency management.
 
 - `manager.py` - Package management
 - `types.py` - Package types
 - `utils.py` - Package utilities
 
+### `resources/` - Resource Discovery
+
+The replaceable loader builds one immutable snapshot from built-in, global,
+project, installed-package, hook-provided, and context-file resources. It
+supports focused overrides and structured diagnostics. Runtime startup and
+`/reload` both consume it.
+
+- `loader.py` - Resource loader protocol, default discovery, and registry application
+- `types.py` - `ResourceContext`, immutable `ResourceSnapshot`, context files, and diagnostics
+
 ### `prompts/` - Prompt Template System
 
 Prompt loading and variable substitution.
@@ -178,10 +189,12 @@ JSON-RPC server for IDE integration.
 
 ### `runtime/` - Agent Runtime
 
-Wires together agent, session, engine, and extensions.
+Wires together agent, session, engine, and extensions with replaceable service
+factories for programmatic embedding.
 
+- `dependencies.py` - Typed dependency factories and creation contexts
 - `service.py` - Main runtime orchestration
-- `types.py` - Runtime state types
+- `types.py` - Runtime state, configuration, and structured startup result types
 
 ### `session/` - Session Management
 
@@ -400,7 +413,7 @@ See [Extensions Guide](extensions.md) for detailed examples.
 ## Code Statistics
 
 - **Total modules**: 205 Python files
-- **Main package**: tau/ (22 subpackages)
+- **Main package**: tau/ (25 subpackages)
 - **Test coverage**: tests/ directory
 - **Lines of code**: ~8,000 LOC (excluding tests and docs)
 - **Type hints**: Full type coverage with mypy/pyright