# agent-store

Minimal agent telemetry store. One process, two paths:

- **OTLP/HTTP** (JSON encoding) → ingest spans/logs/metrics → Postgres
- **MCP streamable-http** → query Postgres → agent introspection tools

## Quick start

```bash
# Local dev
PGHOST=localhost PGPORT=5432 PGUSER=postgres PGPASSWORD=secret PGDATABASE=agentstore \
  bun run src/server.ts
```

## Testing

```bash
# Unit tests only (no DB)
bun test test/otlp-parse.test.ts

# Full integration tests (spins up docker postgres)
bash scripts/test-db.sh

# Or if PG is already running:
PGHOST=localhost PGPORT=5432 PGUSER=postgres PGPASSWORD=secret PGDATABASE=agentstore_test \
  bun test
```

## Env vars

| Var | Default | Description |
|-----|---------|-------------|
| `PORT` | `4318` | HTTP listen port |
| `MCP_PATH` | `/mcp` | MCP endpoint path |
| `DATABASE_URL` | — | Full postgres URL (overrides PGHOST etc.) |
| `PGHOST` | `localhost` | Postgres host |
| `PGPORT` | `5432` | Postgres port |
| `PGUSER` | `postgres` | Postgres user |
| `PGPASSWORD` | `postgres` | Postgres password |
| `PGDATABASE` | `agentstore` | Postgres database |
| `AUDIT_DIR` | `./data` | Directory for ingest audit JSONL files |

## Routes

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/traces` | OTLP/JSON trace ingest |
| `POST` | `/v1/logs` | OTLP/JSON log ingest |
| `POST` | `/v1/metrics` | OTLP/JSON metric ingest |
| `GET` | `/healthz` | Health check (includes PG ping) |
| `ALL` | `/mcp` | MCP streamable-http |

## Schema (`telemetry` schema, auto-migrated on startup)

- **`telemetry.spans`** — OTLP trace spans with resource/scope/attributes as JSONB
- **`telemetry.logs`** — OTLP log records
- **`telemetry.metrics`** — OTLP metric datapoints (gauge/sum/histogram decomposed)

## MCP tools

| Tool | Description |
|------|-------------|
| `query_logs` | Filter logs by service, body, severity, time range |
| `query_traces` | Trace summaries (root span, count, duration, error flag) |
| `get_trace` | All spans for a trace_id, parent-child reconstructable |
| `summarize_activity` | Pre-aggregated per-service stats: spans, errors, top names, daily |
| `list_services` | All services with span/log counts and last_seen |
| `service_schema` | Distinct span names + attribute keys for a service |

`since` param accepts relative (`"7d"`, `"24h"`, `"30m"`) or ISO datetime.

## Docker

```bash
docker build -t agent-store .
docker run -e PGHOST=... -e PGPASSWORD=... -p 4318:4318 agent-store
```