feat(serve): make the API write timeout configurable (kenn-io#1148)

## What

Adds a `--write-timeout` duration flag to `serve` and `pg serve`, making the API
write deadline configurable. The default is unchanged at 30s. A non-positive value
disables the deadline.

## Why

The write deadline was hardcoded at 30s. On large shared datasets the full-history
analytics aggregates (heatmap, activity, usage summary) can exceed it and return
`503` with `{"error":"request timed out"}`, which surfaces as blank "request timed
out" dashboard panels. Operators had no way to raise it. Relates to kenn-io#1147.

## Where to look

- `internal/config/config.go` — the flag is registered on both the `flag` and
  `pflag` serve flag sets (so `serve` and `pg serve` both accept it) and mapped to
  `Config.WriteTimeout` in `applyFlagValue`, mirroring `events-coalesce-interval`.
- `internal/server/middleware.go` — the standard-handler timeout wrapper now
  bypasses `http.TimeoutHandler` when the timeout is non-positive, so `0` disables
  the deadline instead of firing immediately. The typed (Huma) API path already
  had this guard; this brings the two paths into agreement.
- `docs/remote-access.md` — documents raising the timeout for slow aggregates and
  the flag reference row.

## Tradeoffs and limitations

- Raising the timeout treats the symptom. When aggregates are slow enough to need a
  large value, the underlying database-side cost is usually the real fix — for a
  multi-tenant read role, a set-based row-level-security predicate rather than a
  per-row function call. The docs note points there; #1 has the detail.
- Flag only; no new config-file or environment key was added, consistent with the
  neighboring serve duration flags.


Co-authored-by: TechnoPhobe01 <Technophobe01@users.noreply.github.com>

Author: Technophobe01

docs/remote-access.md

@@ -367,6 +367,31 @@ localStorage.removeItem("agentsview-server-url")
 location.reload()
 ```
 
+### Slow Aggregates Behind A Proxy
+
+API responses have a write deadline; a request that exceeds it returns `503`
+with a `{"error":"request timed out"}` body, and affected dashboard panels show
+"request timed out". The default is 30 seconds, which is comfortable for local
+archives but can be tight for large shared datasets — heatmap, activity, and
+usage summaries scan the full message history.
+
+Raise the deadline with `--write-timeout` (a Go duration). The flag is available
+on both the local SQLite server and the PostgreSQL read server:
+
+```bash
+# Local SQLite server
+agentsview serve --write-timeout 120s
+
+# PostgreSQL-backed read server (the multi-tenant / large-dataset case)
+agentsview pg serve --write-timeout 120s
+```
+
+Set it to `0` to disable the deadline entirely. If aggregates are slow enough to
+need a large timeout, that usually points at a database-side cost worth
+investigating first — for a multi-tenant read role, confirm any row-level
+security policy is set-based (`session_id IN (SELECT ...)`) rather than a
+per-row function call, which the query planner cannot hoist into a single join.
+
 ## Managed Caddy Mode
 
 AgentsView can manage a [Caddy](https://caddyserver.com) reverse proxy for
@@ -438,6 +463,7 @@ Changes that affect bind or auth behavior may require a server restart.
 | `--require-auth`    | `false`     | Require a bearer token for API requests             |
 | `--public-url`      |             | Public URL for hostname or proxy access             |
 | `--public-origin`   |             | Trusted browser origin (repeatable/comma-separated) |
+| `--write-timeout`   | `30s`       | API response write deadline; `0` disables it        |
 | `--proxy`           |             | Managed proxy mode (`caddy`)                        |
 | `--caddy-bin`       | `caddy`     | Caddy binary path                                   |
 | `--proxy-bind-host` | `127.0.0.1` | Interface for managed proxy                         |

internal/config/config.go

@@ -1481,6 +1481,10 @@ func RegisterServeFlags(fs *flag.FlagSet) {
 		"events-coalesce-interval", 10*time.Second,
 		"Minimum interval between SSE data_changed broadcasts (0 disables coalescing)",
 	)
+	fs.Duration(
+		"write-timeout", 30*time.Second,
+		"Max time to write an API response before a 503 request-timed-out; raise for slow aggregates over large datasets (0 disables)",
+	)
 }
 
 // RegisterServePFlags registers serve-command flags on fs.
@@ -1545,6 +1549,10 @@ func RegisterServePFlags(fs *pflag.FlagSet) {
 		"events-coalesce-interval", 10*time.Second,
 		"Minimum interval between SSE data_changed broadcasts (0 disables coalescing)",
 	)
+	fs.Duration(
+		"write-timeout", 30*time.Second,
+		"Max time to write an API response before a 503 request-timed-out; raise for slow aggregates over large datasets (0 disables)",
+	)
 }
 
 // applyFlags copies explicitly-set flags from fs into cfg.
@@ -1604,6 +1612,10 @@ func applyFlagValue(cfg *Config, name, value string) {
 		if d, err := time.ParseDuration(value); err == nil {
 			cfg.EventsCoalesceInterval = d
 		}
+	case "write-timeout":
+		if d, err := time.ParseDuration(value); err == nil {
+			cfg.WriteTimeout = d
+		}
 	case "pg":
 		// Read-routing only. The CLI resolver combines this flag
 		// with cfg.PG from env/config and does not persist a new

internal/config/config_test.go

@@ -222,6 +222,35 @@ func loadConfigFromPFlags(t *testing.T, args ...string) (Config, error) {
 	return LoadPFlags(fs)
 }
 
+func TestLoad_WriteTimeout(t *testing.T) {
+	t.Run("defaults to 30s when unset", func(t *testing.T) {
+		cfg, err := loadConfigFromFlags(t)
+		require.NoError(t, err)
+		assert.Equal(t, 30*time.Second, cfg.WriteTimeout)
+	})
+
+	cases := []struct {
+		name  string
+		value string
+		want  time.Duration
+	}{
+		{"raised for slow aggregates", "120s", 120 * time.Second},
+		{"zero disables the deadline", "0s", 0},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name+" (flag)", func(t *testing.T) {
+			cfg, err := loadConfigFromFlags(t, "-write-timeout", tc.value)
+			require.NoError(t, err)
+			assert.Equal(t, tc.want, cfg.WriteTimeout)
+		})
+		t.Run(tc.name+" (pflag)", func(t *testing.T) {
+			cfg, err := loadConfigFromPFlags(t, "--write-timeout", tc.value)
+			require.NoError(t, err)
+			assert.Equal(t, tc.want, cfg.WriteTimeout)
+		})
+	}
+}
+
 func TestLoadMinimal_LoadsAgentBinaryConfig(t *testing.T) {
 	f := newConfigFixture(t)
 	f.WriteConfigText(t, `[agent.claude]

internal/server/middleware.go

@@ -31,6 +31,13 @@ func (s *Server) withTimeout(
 		}
 	}
 
+	// A non-positive write timeout disables the deadline, matching the typed
+	// (Huma) API path. Passing 0 to http.TimeoutHandler would instead fire
+	// immediately and 503 every request.
+	if s.cfg.WriteTimeout <= 0 {
+		return http.HandlerFunc(inner)
+	}
+
 	handler := http.TimeoutHandler(
 		inner, s.cfg.WriteTimeout, msg,
 	)

internal/server/middleware_internal_test.go

@@ -0,0 +1,31 @@
+package server
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// A non-positive write timeout must disable the deadline instead of wrapping the
+// handler in http.TimeoutHandler with a 0 duration, which would fire immediately
+// and 503 every request.
+func TestWithTimeout_NonPositiveDisablesDeadline(t *testing.T) {
+	t.Parallel()
+	s := testServer(t, 0)
+
+	called := false
+	h := s.withTimeout(func(w http.ResponseWriter, _ *http.Request) {
+		called = true
+		w.WriteHeader(http.StatusOK)
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/recall/entries", nil)
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+
+	require.True(t, called, "handler should run when the write timeout is disabled")
+	assert.Equal(t, http.StatusOK, w.Code)
+}