feat: hosted collector endpoint — managed `agent-strace server` with free tier

[Siddhant-K-code]

Problem

agent-strace server works well for local and self-hosted setups. But running a persistent collector requires provisioning infrastructure, managing uptime, and handling storage — which is friction for teams that just want traces to land somewhere reliable without ops work.

The current flow for multi-agent or CI use cases:

agent → AGENT_STRACE_ENDPOINT=http://my-server:4317 → self-hosted collector

The self-hosted step is a barrier. You need a machine, a process manager, persistent storage, and a public endpoint. For many users, that's more work than the tracing itself.

---

Proposed solution

A hosted collector endpoint that accepts the same HTTP API as agent-strace server — no client changes required.

# Today (self-hosted)
AGENT_STRACE_ENDPOINT=http://localhost:4317 python my_agent.py

# With hosted collector (no other changes)
AGENT_STRACE_ENDPOINT=https://collector.agent-strace.dev python my_agent.py

The client (agent-strace) does not change. The server-side collector protocol is already defined. This is purely an infrastructure addition.

---

What it enables

• CI/CD tracing — agents running in ephemeral containers can push traces to a persistent endpoint without any infrastructure setup
• Multi-machine correlation — traces from multiple agents across different machines land in one place, correlated by session ID
• Team sharing — agent-strace share <id> already generates a shareable HTML replay; a hosted collector makes the underlying data accessible without self-hosting
• Persistent history — local .agent-traces/ directories get cleaned up; a hosted collector retains session history across machines and reinstalls

---

Scope

Collector API (unchanged from agent-strace server)

The hosted endpoint implements the same API already documented in docs/server.md:

• POST /events — ingest NDJSON event batches
• GET /sessions — list sessions
• GET /sessions/{id} — fetch session events
• GET /events/stream — SSE stream for live panel

No protocol changes. Existing --stream-to and AGENT_STRACE_ENDPOINT flags work without modification.

Authentication

API key passed as Authorization: Bearer <key> header. The existing --stream-headers flag on agent-strace watch already supports custom headers, so no CLI changes needed.

Storage

Sessions stored per API key. Retention policy TBD (e.g. 30 days on free tier).

Free tier

A free tier with reasonable limits (session count, retention, storage) so individual developers and open-source projects can use it without a credit card.

---

Out of scope for this issue

• Web UI / dashboard (the VS Code extension already covers session browsing)
• Team management / org accounts
• Custom retention policies
• SLA guarantees

---

Implementation notes

• The server implementation in src/agent_trace/server.py is the reference. The hosted version is the same logic behind a persistent process with auth middleware added.
• Deployment target: any platform that supports persistent HTTP services and file/object storage (Fly.io, Railway, Render — all viable).
• The agent-strace server local mode stays unchanged. This is additive.

---

Acceptance criteria

• Hosted endpoint accepts the same NDJSON event batches as agent-strace server
• Authentication via API key (Authorization: Bearer)
• AGENT_STRACE_ENDPOINT=https://collector.agent-strace.dev works with no other client changes
• Sessions retrievable via GET /sessions and GET /sessions/{id}
• SSE stream works for VS Code live streaming panel
• Free tier available without credit card
• Docs updated: docs/server.md gets a "Hosted collector" section alongside the self-hosted guide

[Siddhant-K-code]

The client side is already fully ready — AGENT_STRACE_ENDPOINT, AGENT_STRACE_AUTH_KEY (added in #131), and --stream-headers all work today. No changes needed to this package when the hosted endpoint goes live.

Suggestion: implement the infrastructure in a separate repo — e.g. agent-strace/agent-strace-collector. Reasons:

• The deployment work (persistent HTTP service, storage backend, domain, free tier billing) has a completely different lifecycle from the Python package and VS Code extension
• Keeping infra separate avoids mixing deployment configs, secrets, and cloud provider tooling into this repo
• The collector server code in src/agent_trace/server.py can be imported directly as the reference implementation — no duplication needed
• CI/CD, versioning, and release cadence for infra are different from library releases

What's been done in this repo for #129:

• PR feat(server): API key authentication for collector (#130) #131 adds agent-strace server --auth-key and AGENT_STRACE_AUTH_KEY (the auth mechanism the hosted endpoint needs)
• PR docs(server): add hosted collector section (#129) #132 adds a "Hosted collector" section to docs/server.md with a placeholder link to the infra repo and the one-line client change needed on the client side

Once the infra repo exists, we can update the docs link and close this issue.

[Siddhant-K-code]

Status update — several pieces of the infrastructure this depends on have now shipped:

• agent-strace server — self-hosted collector, fully working
• agent-strace auth login — SSO/OIDC for hosted collector (feat: SSO (SAML/OIDC) for hosted collector #146)
• agent-strace rbac assign — org/project access control (feat: RBAC — org and project level access control #147)
• agent-strace compliance export — compliance evidence export (feat: compliance evidence export (agent-strace compliance export) #144)

What's still pending from this issue: the hosted endpoint (collector.agent-strace.dev) — the managed infrastructure that accepts events without self-hosting. That's the remaining blocker for CI/CD tracing from ephemeral containers and the free-tier story.

Keeping open and tagging for the hosted tier milestone.

[Siddhant-K-code]

Triage after clearing the repo-local feature issues:

This is not safely closable with a code-only PR in agent-strace. The local collector protocol and bearer auth path already exist in src/agent_trace/server.py, and docs/server.md already marks the managed endpoint as planned. The remaining acceptance criteria require operating infrastructure: https://collector.agent-strace.dev, API key issuance, per-key storage/retention, SSE availability, and a free tier.

Suggested next step: provision the hosted service first, then use this issue to track the deployment/configuration checklist. A follow-up repo PR would only be needed if the deployed service exposes a protocol difference from agent-strace server.