Improve agent-facing history endpoints (Phase 1)

- Fix /api/history/{type} to search the full persistent store instead of
  only the bounded in-memory ring buffer, so filtered history isn't
  silently truncated.
- Add structured type/since/until filters to /api/history/search and
  /api/history/wait, alongside the existing free-text query.
- Add GET /api/traces/{traceId} to fetch all entries for a trace in one
  call instead of relying on substring search.
- Rate-limit /api/history/wait per client IP.
- Add docs/PLAN.md tracking the phased improvement plan; update README
  and agents_example.md for the new/changed endpoints.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

internal/storage/file_store.go

@@ -42,11 +42,40 @@ func (fs *FileStore) Append(ctx context.Context, entry websocket.HistoryEntry) e
 
 // GetHistory retrieves historical entries from the file store.
 func (fs *FileStore) GetHistory(ctx context.Context, limit int) ([]websocket.HistoryEntry, error) {
-	return fs.Search(ctx, "", limit)
+	return fs.Search(ctx, SearchOptions{}, limit)
 }
 
-// Search searches for historical entries in the file store matching the query.
-func (fs *FileStore) Search(ctx context.Context, query string, limit int) ([]websocket.HistoryEntry, error) {
+// entryHead is used to cheaply inspect an entry's type/timestamp without
+// unmarshaling the (potentially large) Data payload.
+type entryHead struct {
+	Type      string `json:"type"`
+	Timestamp int64  `json:"timestamp"`
+}
+
+// matches reports whether the given line satisfies the type/time filters in opts.
+// The free-text Query filter is applied separately by the caller against the raw line.
+func (opts SearchOptions) matches(line string) bool {
+	if opts.Type == "" && opts.Since == 0 && opts.Until == 0 {
+		return true
+	}
+	var head entryHead
+	if err := json.Unmarshal([]byte(line), &head); err != nil {
+		return false
+	}
+	if opts.Type != "" && head.Type != opts.Type {
+		return false
+	}
+	if opts.Since != 0 && head.Timestamp < opts.Since {
+		return false
+	}
+	if opts.Until != 0 && head.Timestamp > opts.Until {
+		return false
+	}
+	return true
+}
+
+// Search searches for historical entries in the file store matching opts.
+func (fs *FileStore) Search(ctx context.Context, opts SearchOptions, limit int) ([]websocket.HistoryEntry, error) {
 	if limit <= 0 {
 		limit = 50 // Default to a manageable number
 	}
@@ -70,16 +99,20 @@ func (fs *FileStore) Search(ctx context.Context, query string, limit int) ([]web
 	scanner.Buffer(buf, maxCapacity)
 
 	// Lowercase query for case-insensitive search
-	lowerQuery := strings.ToLower(query)
+	lowerQuery := strings.ToLower(opts.Query)
 
 	for scanner.Scan() {
 		line := scanner.Text()
-		if query == "" || strings.Contains(strings.ToLower(line), lowerQuery) {
-			matchingLines = append(matchingLines, line)
-			// Only keep the most recent 'limit' matches to save memory
-			if len(matchingLines) > limit {
-				matchingLines = matchingLines[1:]
-			}
+		if opts.Query != "" && !strings.Contains(strings.ToLower(line), lowerQuery) {
+			continue
+		}
+		if !opts.matches(line) {
+			continue
+		}
+		matchingLines = append(matchingLines, line)
+		// Only keep the most recent 'limit' matches to save memory
+		if len(matchingLines) > limit {
+			matchingLines = matchingLines[1:]
 		}
 	}