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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tau-coding-agent
-Version: 0.4.5
+Version: 0.4.6
 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.4.5 → tau_coding_agent-0.4.6}/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.6}/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
@@ -786,7 +814,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 +1451,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 +1472,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.6}/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