feat(traces): add search and advanced filters

Closes #152

docs/10-tracing-observability.md

@@ -193,10 +193,20 @@ worker.Stop()
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
+| `q` | string | Contains search across trace ID, trace previews, session/channel labels, joined agent/channel labels, and span previews/tool names |
 | `agent_id` | UUID | Filter by agent |
 | `user_id` | string | Filter by user |
-| `status` | string | Filter by status (running, success, error, cancelled) |
-| `from` / `to` | timestamp | Date range filter |
+| `session_key` | string | Filter by session key |
+| `status` | string | Filter by status (running, completed, error, cancelled) |
+| `channel` | string | Filter by raw channel |
+| `agent` | string | Contains search over agent display name and key |
+| `channel_query` | string | Contains search over tenant-scoped channel instance labels |
+| `from` / `to` | timestamp | `start_time` range filter; `from` inclusive, `to` exclusive |
+| `min_input_tokens` / `max_input_tokens` | int | Input token range |
+| `min_output_tokens` / `max_output_tokens` | int | Output token range |
+| `min_tool_calls` / `max_tool_calls` | int | Tool-call count range |
+| `tool_name` | string | Contains search over span tool names |
+| `has_tool_calls` | boolean | Filter traces with or without tool calls |
 | `limit` | int | Page size (default 50) |
 | `offset` | int | Pagination offset |
 

docs/18-http-api.md

@@ -1358,7 +1358,26 @@ LLM call tracing and cost analysis.
 | `GET` | `/v1/traces/{traceID}/export` | Export trace tree (gzipped JSON) |
 | `GET` | `/v1/runs/{runID}/timeline` | Get persisted run archive timeline items |
 
-**Filters:** `agent_id`, `user_id`, `session_key`, `status`, `channel`
+`GET /v1/traces` query params:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `q` | string | Contains search across trace ID, trace name, input/output previews, session key, raw channel, joined agent/channel labels, and span tool/input/output previews |
+| `agent_id` | UUID | Exact agent UUID filter |
+| `user_id` | string | Exact user filter; non-admin callers are always forced to their own user scope |
+| `session_key` | string | Exact session key filter |
+| `status` | string | Exact trace status filter |
+| `channel` | string | Exact raw channel filter |
+| `agent` | string | Contains search over joined agent display name and key |
+| `channel_query` | string | Contains search over tenant-scoped channel instance name, display name, and type |
+| `from` / `to` | RFC 3339 timestamp | Start-time range; `from` is inclusive, `to` is exclusive |
+| `min_input_tokens` / `max_input_tokens` | int | Input token range |
+| `min_output_tokens` / `max_output_tokens` | int | Output token range |
+| `min_tool_calls` / `max_tool_calls` | int | Tool-call count range |
+| `tool_name` | string | Contains search over span tool names |
+| `has_tool_calls` | boolean | Convenience filter for traces with or without tool calls |
+| `limit` | int | Page size, default 50, max 200 |
+| `offset` | int | Pagination offset |
 
 `GET /v1/traces/follow` requires `session_key` or `agent_id`. Query params: `session_key`, `agent_id`, `status`, `channel`, `since` (RFC 3339), `limit` (default 50, max 200), `include_spans` (default false). Non-admin callers only see their own traces. When `since` is provided, the server returns traces matching existing filters and `(created_at > since OR end_time > since OR status = "running")`.
 

docs/project-changelog.md

@@ -6,6 +6,23 @@ Significant changes, features, and fixes in reverse chronological order.
 
 ## 2026-06-11
 
+### Trace search and advanced filters (issue #152)
+
+**Changes**
+
+- Extended `GET /v1/traces` with keyword search, partial Trace ID search, date
+  ranges, token ranges, tool-call filters, and agent/channel label search.
+- Added equivalent PostgreSQL and SQLite query-builder behavior with tenant
+  guards on joined channel/span search.
+- Added Web Traces search/filter controls with active filter chips.
+
+**Tests**
+
+- Added HTTP contract coverage for advanced trace filter parsing and user scope.
+- Added PostgreSQL and SQLite where-builder coverage for search, ranges, tool
+  filters, tenant predicates, and wildcard escaping.
+- Added Web filter serialization and trace i18n key coverage.
+
 ### Secure CLI GitHub credential runtime diagnostics (issues #138, #151)
 
 **Fixes**