feat: add 18 new MCP tools for session management and observability

CLAUDE.md

@@ -84,7 +84,7 @@ uv run python -m mcp_acp.server
 ### Three-Layer Design
 
 **1. MCP Server Layer (`server.py`)**
-- Exposes 8 MCP tools via stdio protocol
+- Exposes 26 MCP tools via stdio protocol
 - Inline JSON Schema definitions per tool
 - if/elif dispatch in `call_tool()` maps tool names to handlers
 - Server-layer confirmation enforcement for destructive bulk operations
@@ -98,7 +98,7 @@ uv run python -m mcp_acp.server
 **3. Formatting Layer (`formatters.py`)**
 - Converts raw API responses to user-friendly text
 - Handles dry-run output, error states, bulk results
-- Format functions: `format_result()`, `format_bulk_result()`, `format_sessions_list()`, etc.
+- Format functions: `format_result()`, `format_bulk_result()`, `format_sessions_list()`, `format_session_created()`, `format_logs()`, `format_transcript()`, `format_metrics()`, `format_labels()`, `format_login()`, etc.
 
 ### Data Flow
 
@@ -382,6 +382,15 @@ From `client.py`:
 ```python
 MAX_BULK_ITEMS = 3
 DEFAULT_TIMEOUT = 30.0  # seconds (httpx request timeout)
+
+LABEL_VALUE_PATTERN = re.compile(r"^[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?$")
+
+SESSION_TEMPLATES = {
+    "triage": {"workflow": "triage", "llmConfig": {"model": "claude-sonnet-4", "temperature": 0.7}},
+    "bugfix": {"workflow": "bugfix", "llmConfig": {"model": "claude-sonnet-4", "temperature": 0.3}},
+    "feature": {"workflow": "feature-development", "llmConfig": {"model": "claude-sonnet-4", "temperature": 0.5}},
+    "exploration": {"workflow": "codebase-exploration", "llmConfig": {"model": "claude-sonnet-4", "temperature": 0.8}},
+}
 ```
 
 ---
@@ -412,11 +421,9 @@ DEFAULT_TIMEOUT = 30.0  # seconds (httpx request timeout)
 ## Documentation
 
 - **[README.md](README.md)** - Project overview, quick start, and usage guide
-- **[API_REFERENCE.md](API_REFERENCE.md)** - Complete tool specifications (8 tools)
+- **[API_REFERENCE.md](API_REFERENCE.md)** - Complete tool specifications (26 tools)
 - **[SECURITY.md](SECURITY.md)** - Security features and threat model
 
-See [issue #27](https://github.com/ambient-code/mcp/issues/27) for 21 planned additional tools.
-
 ---
 
 ## Notes for Future Claude Instances
@@ -437,9 +444,17 @@ See [issue #27](https://github.com/ambient-code/mcp/issues/27) for 21 planned ad
 
 ### When Adding New Tools
 
-- See [issue #27](https://github.com/ambient-code/mcp/issues/27) for the backlog of planned tools
+- See issues [#28](https://github.com/ambient-code/mcp/issues/28) and [#29](https://github.com/ambient-code/mcp/issues/29) for the remaining planned tools
 - Follow the 4-step pattern: client method -> tool definition -> dispatch branch -> tests
-- All API calls go through `_request()` method
+- All API calls go through `_request()` or `_request_text()` methods
+
+### When Working with Label Operations
+
+- Labels are validated via `_validate_labels()` using `LABEL_VALUE_PATTERN`
+- Label keys and values: 1-63 chars, alphanumeric, dashes, dots, underscores
+- Label selectors are built as `key1=value1,key2=value2` query strings
+- Bulk label/unlabel operations use `_validate_bulk_operation()` for the 3-item limit
+- "By label" bulk operations first resolve labels to session names via `_run_bulk_by_label()`
 
 ### Code Quality Standards
 

README.md

@@ -52,21 +52,62 @@ List my ACP sessions
 
 ## Features
 
+### Session Management
+
 | Tool | Description |
 |------|-------------|
 | `acp_list_sessions` | List/filter sessions by status, age, with sorting and limits |
 | `acp_get_session` | Get detailed session information by ID |
 | `acp_create_session` | Create sessions with custom prompts, repos, model selection, and timeout |
+| `acp_create_session_from_template` | Create sessions from predefined templates (triage/bugfix/feature/exploration) |
 | `acp_delete_session` | Delete sessions with dry-run preview |
+| `acp_restart_session` | Restart a stopped session |
+| `acp_clone_session` | Clone an existing session's configuration into a new session |
+| `acp_update_session` | Update session metadata (display name, timeout) |
+
+### Observability
+
+| Tool | Description |
+|------|-------------|
+| `acp_get_session_logs` | Retrieve container logs for a session |
+| `acp_get_session_transcript` | Retrieve conversation history (JSON or Markdown) |
+| `acp_get_session_metrics` | Get usage statistics (tokens, duration, tool calls) |
+
+### Labels
+
+| Tool | Description |
+|------|-------------|
+| `acp_label_resource` | Add labels to a session for organizing and filtering |
+| `acp_unlabel_resource` | Remove labels from a session by key |
+| `acp_list_sessions_by_label` | List sessions matching label selectors |
+| `acp_bulk_label_resources` | Add labels to multiple sessions (max 3) |
+| `acp_bulk_unlabel_resources` | Remove labels from multiple sessions (max 3) |
+
+### Bulk Operations
+
+| Tool | Description |
+|------|-------------|
 | `acp_bulk_delete_sessions` | Delete multiple sessions (max 3) with confirmation and dry-run |
+| `acp_bulk_stop_sessions` | Stop multiple running sessions (max 3) |
+| `acp_bulk_restart_sessions` | Restart multiple stopped sessions (max 3) |
+| `acp_bulk_delete_sessions_by_label` | Delete sessions matching label selectors (max 3 matches) |
+| `acp_bulk_stop_sessions_by_label` | Stop sessions matching label selectors (max 3 matches) |
+| `acp_bulk_restart_sessions_by_label` | Restart sessions matching label selectors (max 3 matches) |
+
+### Cluster Management
+
+| Tool | Description |
+|------|-------------|
 | `acp_list_clusters` | List configured cluster aliases |
 | `acp_whoami` | Check current configuration and authentication status |
 | `acp_switch_cluster` | Switch between configured clusters |
+| `acp_login` | Authenticate to a cluster with a Bearer token |
 
 **Safety Features:**
 
 - **Dry-Run Mode** — All mutating operations support `dry_run` for safe preview before executing
 - **Bulk Operation Limits** — Maximum 3 items per bulk operation with confirmation requirement
+- **Label Validation** — Labels must be 1-63 alphanumeric characters, dashes, dots, or underscores
 
 ---
 
@@ -218,19 +259,42 @@ Show AgenticSession session-name in my-workspace
 # Create a session
 Create a new ACP session with prompt "Run all unit tests and report results"
 
+# Create from template
+Create an ACP session from the bugfix template called "fix-auth-issue"
+
+# Restart / clone
+Restart ACP session my-stopped-session
+Clone ACP session my-session as "my-session-v2"
+
+# Update session metadata
+Update ACP session my-session display name to "Production Test Runner"
+
+# Observability
+Show logs for ACP session my-session
+Get transcript for ACP session my-session in markdown format
+Show metrics for ACP session my-session
+
+# Labels
+Label ACP session my-session with env=staging and team=platform
+Remove label env from ACP session my-session
+List ACP sessions with label team=platform
+
 # Delete with dry-run (safe!)
 Delete test-session from my-workspace in dry-run mode
 
 # Actually delete
 Delete test-session from my-workspace
 
-# Bulk delete (dry-run first)
+# Bulk operations (dry-run first)
 Delete these sessions: session-1, session-2, session-3 from my-workspace (dry-run first)
+Stop all sessions with label env=test
+Restart sessions with label team=platform
 
 # Cluster operations
 Check my ACP authentication
 List my ACP clusters
 Switch to ACP cluster vteam-prod
+Login to ACP cluster vteam-stage with token
 ```
 
 ### Trigger Keywords
@@ -247,10 +311,22 @@ Include one of these keywords so your MCP client routes the request to ACP: **AC
 | Filter age | `List sessions older than 7d in PROJECT` |
 | Get details | `Get details for ACP session SESSION` |
 | Create | `Create ACP session with prompt "..."` |
+| Create from template | `Create ACP session from bugfix template` |
+| Restart | `Restart ACP session SESSION` |
+| Clone | `Clone ACP session SESSION as "new-name"` |
+| Update | `Update ACP session SESSION timeout to 1800` |
+| View logs | `Show logs for ACP session SESSION` |
+| View transcript | `Get transcript for ACP session SESSION` |
+| View metrics | `Show metrics for ACP session SESSION` |
+| Add labels | `Label ACP session SESSION with env=test` |
+| Remove labels | `Remove label env from ACP session SESSION` |
+| Filter by label | `List ACP sessions with label team=platform` |
 | Delete (dry) | `Delete SESSION in PROJECT (dry-run)` |
 | Delete (real) | `Delete SESSION in PROJECT` |
 | Bulk delete | `Delete session-1, session-2 in PROJECT` |
+| Bulk by label | `Stop sessions with label env=test` |
 | List clusters | `Use acp_list_clusters` |
+| Login | `Login to ACP cluster CLUSTER` |
 
 ---
 
@@ -263,11 +339,29 @@ For complete API specifications including input schemas, output formats, and beh
 | **Session** | `acp_list_sessions` | List/filter sessions |
 | | `acp_get_session` | Get session details |
 | | `acp_create_session` | Create session with prompt |
+| | `acp_create_session_from_template` | Create from template |
 | | `acp_delete_session` | Delete with dry-run support |
+| | `acp_restart_session` | Restart stopped session |
+| | `acp_clone_session` | Clone session configuration |
+| | `acp_update_session` | Update display name or timeout |
+| **Observability** | `acp_get_session_logs` | Retrieve container logs |
+| | `acp_get_session_transcript` | Get conversation history |
+| | `acp_get_session_metrics` | Get usage statistics |
+| **Labels** | `acp_label_resource` | Add labels to session |
+| | `acp_unlabel_resource` | Remove labels by key |
+| | `acp_list_sessions_by_label` | Filter sessions by labels |
+| | `acp_bulk_label_resources` | Bulk add labels (max 3) |
+| | `acp_bulk_unlabel_resources` | Bulk remove labels (max 3) |
 | **Bulk** | `acp_bulk_delete_sessions` | Delete multiple sessions (max 3) |
+| | `acp_bulk_stop_sessions` | Stop multiple sessions (max 3) |
+| | `acp_bulk_restart_sessions` | Restart multiple sessions (max 3) |
+| | `acp_bulk_delete_sessions_by_label` | Delete by label (max 3) |
+| | `acp_bulk_stop_sessions_by_label` | Stop by label (max 3) |
+| | `acp_bulk_restart_sessions_by_label` | Restart by label (max 3) |
 | **Cluster** | `acp_list_clusters` | List configured clusters |
 | | `acp_whoami` | Check authentication status |
 | | `acp_switch_cluster` | Switch cluster context |
+| | `acp_login` | Authenticate with Bearer token |
 
 ---
 
@@ -364,12 +458,10 @@ See [CLAUDE.md](CLAUDE.md#development-commands) for contributing guidelines.
 
 ## Roadmap
 
-Current implementation provides 8 core tools. See [issue #27](https://github.com/ambient-code/mcp/issues/27) for 21 planned additional tools covering:
+Current implementation provides 26 tools. 3 tools remain planned:
 
-- Session lifecycle (restart, clone, templates, update, export)
-- Observability (logs, transcripts, metrics)
-- Label management and advanced bulk operations
-- Cluster and workflow management
+- Session export ([issue #28](https://github.com/ambient-code/mcp/issues/28))
+- Workflow management ([issue #29](https://github.com/ambient-code/mcp/issues/29))
 
 ---
 
@@ -389,13 +481,13 @@ Current implementation provides 8 core tools. See [issue #27](https://github.com
 **Code**: Production-Ready |
 **Tests**: All Passing |
 **Security**: Input validation, gateway enforcement, token security |
-**Tools**: 8 implemented ([21 more planned](https://github.com/ambient-code/mcp/issues/27))
+**Tools**: 26 implemented ([3 more planned](https://github.com/ambient-code/mcp/issues/28))
 
 ---
 
 ## Documentation
 
-- **[API_REFERENCE.md](API_REFERENCE.md)** — Full API specifications for all 8 tools
+- **[API_REFERENCE.md](API_REFERENCE.md)** — Full API specifications for all 26 tools
 - **[SECURITY.md](SECURITY.md)** — Security features, threat model, and best practices
 - **[CLAUDE.md](CLAUDE.md)** — System architecture and development guide