synops/docs/infra/agent_api.md

# Agent API — Claude sitt strukturerte grensesnitt mot maskinrommet

## Bakgrunn

I dag snakker Claude med systemet via `claude -p` med hele konteksten
bakt inn som en tekststreng. Det fungerer for enkle chat-svar, men
skalerer ikke:

- Prompten blir enorm når spec + historikk + graf-kontekst skal med
- Claude kan ikke *hente mer info* underveis — alt må være i prompten
- Claude kan ikke *gjøre handlinger* (oppdatere spec, søke, sjekke status)
- Ingen struktur — alt er fritekst, ingen validering

## Konsept

Et sett med maskinrommet-endepunkter designet for agenten — ikke for
brukere. Autentisert med agent-token (samme som i `agent_identities`).
Gir Claude strukturert tilgang til grafen, spesifikasjoner og handlinger.

## Endepunkter

### Lesing (kontekst)

#### `GET /agent/context`
Hent alt Claude trenger for å svare i en samtale.

```
GET /agent/context?communication_id=<uuid>
```

Returnerer:
```json
{
  "communication": { "id": "...", "title": "..." },
  "participants": [{ "id": "...", "title": "...", "node_kind": "..." }],
  "messages": [{ "id": "...", "content": "...", "sender": "...", "timestamp": "..." }],
  "spec": { "id": "...", "content": "...", "feature_key": "..." } | null,
  "related_nodes": [{ "id": "...", "title": "...", "edge_type": "..." }]
}
```

Fordel over dagens løsning: én request, strukturert, med spec og
relaterte noder inkludert. Maskinrommet bestemmer hva som er relevant.

#### `GET /agent/node`
Hent en spesifikk node med edges.

```
GET /agent/node?id=<uuid>&depth=1
```

Returnerer noden med edges i angitt dybde. Nyttig når Claude trenger
mer kontekst enn det som var i `context`-svaret.

#### `GET /agent/search`
Søk i grafen.

```
GET /agent/search?q=<tekst>&node_kind=content&limit=10
```

PG fulltekstsøk over nodes.content + nodes.title. Filtrering på
node_kind, visibility, samling. Returnerer noder med relevans-score.

#### `GET /agent/feature_status`
Sjekk implementeringsstatus for en feature.

```
GET /agent/feature_status?key=lydstudio
```

Returnerer:
```json
{
  "feature_key": "lydstudio",
  "spec_node_id": "...",
  "tasks": [
    { "id": "17.1", "description": "...", "status": "done" },
    { "id": "17.2", "description": "...", "status": "todo" }
  ],
  "recent_commits": ["..."],
  "feedback_summary": "3 brukere har gitt feedback, 1 ubesvart"
}
```

Henter fra tasks.md (parser markdown), git log, og feedback-chat.

#### `GET /agent/tasks`
Hent gjeldende oppgavestatus.

```
GET /agent/tasks?phase=14&status=todo
```

Parser tasks.md og returnerer strukturert. Filtrer på fase og status.

### Skriving (handlinger)

#### `POST /agent/update_spec`
Oppdater en spec-node.

```json
{
  "node_id": "...",
  "content": "oppdatert markdown...",
  "reason": "Integrert feedback fra bruker X om Y"
}
```

Oppdaterer noden i STDB + PG. Logger endringen i `ai_usage_log`
med `job_type: 'spec_update'`. Oppretter `revision`-node med
forrige versjon for historikk.

#### `POST /agent/respond`
Send et svar i en samtale (erstatter dagens direkte STDB-skriving).

```json
{
  "communication_id": "...",
  "content": "svarteksten",
  "metadata": { "confidence": 0.9, "sources": ["node_id_1"] }
}
```

Maskinrommet håndterer node-opprettelse, edges, og STDB-synk.
Metadata kan inkludere kildereferanser som frontend kan vise.

#### `POST /agent/suggest_edges`
Foreslå nye edges basert på innholdsanalyse.

```json
{
  "source_id": "...",
  "suggestions": [
    { "target_id": "...", "edge_type": "mentions", "confidence": 0.85 },
    { "target_id": "...", "edge_type": "related_to", "confidence": 0.7 }
  ]
}
```

Lagres som forslag (`metadata.suggested: true`) — bruker eller admin
godkjenner. Over en viss confidence-terskel kan de auto-godkjennes.

## Autentisering

Agent-endepunktene bruker agent-token fra `agent_identities`-tabellen.
Samme token som brukes for STDB-tilkobling. Header:

```
Authorization: Bearer <agent_token>
```

Maskinrommet validerer at tokenet tilhører en aktiv agent
(`is_active = true`). Agentens `node_id` brukes som `created_by`
for alle handlinger.

## Integrasjon med `claude -p`

Dagens `agent_respond`-jobb kaller `claude -p` med en tekstprompt.
Med Agent API endres flyten:

### Før (nåværende)
```
melding → agent_respond-jobb → bygg prompt (SQL) → claude -p → parse svar → skriv STDB+PG
```

### Etter (med Agent API)
```
melding → agent_respond-jobb → GET /agent/context → claude -p med tool-definisjon → claude bruker tools → POST /agent/respond
```

Claude får tool-definisjoner i prompten og kan kalle Agent API via
tool-use i JSON-output. Maskinrommet parser tool-calls og utfører dem.

Alternativt: Claude Code har allerede tool-bruk via Bash. Agent API
kan eksponeres som `curl`-kommandoer som Claude kaller direkte.

## Prioritering

### Fase 1 (umiddelbar verdi)
- `GET /agent/context` — erstatter SQL-i-prompten, gir spec-kontekst
- `POST /agent/respond` — strukturert svar med metadata

### Fase 2 (bedre feedback-løkke)
- `GET /agent/feature_status` — Claude kan gi informerte statussvar
- `POST /agent/update_spec` — Claude kan integrere feedback direkte
- `GET /agent/search` — Claude kan finne relevant kontekst selv

### Fase 3 (proaktiv agent)
- `POST /agent/suggest_edges` — automatisk grafbygging
- `GET /agent/tasks` — Claude kan rapportere på fremdrift
- Periodiske jobber: digest, spec-synk, feedback-oppsummering

## Bygger på
- Agent-infrastruktur (`docs/infra/claude_agent.md`)
- Feature feedback (`docs/features/feature_feedback.md`)
- Jobbkø (`docs/infra/jobbkø.md`)
- AI Gateway (`docs/infra/ai_gateway.md`)