synops/docs/infra/claude_agent.md

Infrastruktur: Claude som chat-deltaker

Oversikt

Claude deltar i samtaler som en agent-node i grafen. Når en bruker sender en melding i en kommunikasjonsnode der Claude er deltaker, trigger maskinrommet en agent_respond-jobb som delegerer til synops-respond CLI-verktøyet.

Arkitektur

Bruker sender melding (via frontend)
  → create_node() i maskinrommet
  → sjekker: har kommunikasjonsnoden en agent-deltaker?
  → ja: enqueue agent_respond-jobb (prioritet 8)
  → jobbkø-worker plukker opp (poll hvert 2s)
  → maskinrommet: kill switch, rate limit, loop-prevensjon
  → spawner: synops-respond --communication-id ... --write
    → henter meldingshistorikk + kontekst fra PG
    → bygger prompt
    → kaller: claude -p "<prompt>" --output-format json
    → oppretter svar-node i PG, logger ai_usage + resource_usage
    → returnerer JSON med reply_node_id + response_text
  → PG NOTIFY propagerer til frontend via WebSocket
  → frontend viser melding i sanntid

Ansvarsdeling (unix-filosofi):

• Maskinrommet: Auth, kill switch, rate limiting, loop-prevensjon, env-videresending
• synops-respond: Kontekst-henting, URL-deteksjon, synops-clip-kall, prompt-bygging, claude-kall, PG-skriving
• synops-clip: Artikkelhenting, parsing, paywall-deteksjon, AI-oppsummering, node-opprettelse

Latens: ~3-5 sekunder uten URL, ~10-20 sekunder med URL (synops-clip + LLM-oppsummering).

URL-klipping i chat (oppgave 25.3)

Når en bruker limer inn en URL i chatten, gjenkjenner synops-respond URL-en og kaller synops-clip --write automatisk før Claude svarer:

Bruker: "Sjekk denne: https://nrk.no/artikkel"
  → synops-respond detekterer URL med regex
  → spawner: synops-clip --url ... --write --created-by <bruker>
  → synops-clip henter, parser, oppsummerer, oppretter node
  → resultat (tittel, oppsummering, paywall) inkluderes i prompt
  → Claude svarer med oppsummering basert på klipp-kontekst

Ved betalingsmur: Claude informerer om at artikkelen er bak betalingsmur, presenterer det som er tilgjengelig (tittel/ingress), og ber brukeren lime inn innholdet om de vil dele resten.

Begrensninger: Maks 3 URL-er per melding. 60 sekunders timeout per klipp.

Noder og tabeller

Claude-noden

• UUID: d3eebc99-9c0b-4ef8-bb6d-6bb9bd380a44
• node_kind: agent
• visibility: discoverable

agent_identities

Kobler agent-noder til konfigurasjon og nøkkel.

Felt	Verdi
agent_key	claude-main
agent_type	claude
config	max_context_messages, rate_limit_per_hour, etc.

agent_permissions

Autorisasjonsnivåer per bruker/agent-par.

Nivå	Betydning
direct	Kan bestille endringer som implementeres direkte
propose	Kan foreslå endringer som krever godkjenning

ai_usage_log

Logger hvert agent-svar med timestamps, job_id, og kommunikasjons-ID.

Sikkerhet

Mekanisme	Beskrivelse
Kill switch	agent_identities.is_active = false stopper all aktivitet
Rate limiting	Maks 60 responser per time (konfigurerbart)
Loop-prevensjon	Stopper hvis siste 3 meldinger er fra agenten
Egne meldinger	Svarer aldri på egne meldinger (sjekk i trigger)

Oppsett av ny chat med Claude

-- 1. Opprett kommunikasjonsnode
INSERT INTO nodes (id, node_kind, title, visibility, metadata, created_by)
VALUES ('<uuid>', 'communication', 'Min chat med Claude', 'hidden', '{}', '<bruker-uuid>');

-- 2. Legg til bruker som owner
INSERT INTO edges (id, source_id, target_id, edge_type, metadata, system, created_by)
VALUES ('<uuid>', '<bruker-uuid>', '<comm-uuid>', 'owner', '{}', false, '<bruker-uuid>');

-- 3. Legg til Claude som member_of
INSERT INTO edges (id, source_id, target_id, edge_type, metadata, system, created_by)
VALUES ('<uuid>', 'd3eebc99-9c0b-4ef8-bb6d-6bb9bd380a44', '<comm-uuid>', 'member_of', '{}', false, '<bruker-uuid>');

-- 4. Recompute access
SELECT recompute_access('<bruker-uuid>', '<comm-uuid>', 'owner', '<owner-edge-uuid>');
SELECT recompute_access('d3eebc99-9c0b-4ef8-bb6d-6bb9bd380a44', '<comm-uuid>', 'member', '<member-edge-uuid>');

Etter dette vil alle meldinger i chatten automatisk trigge Claude-svar.

Drift

Maskinrommet kjører som systemd-tjeneste direkte på hosten:

sudo systemctl status maskinrommet   # status
sudo systemctl restart maskinrommet  # restart etter ny build
sudo journalctl -u maskinrommet -f   # live-logger

Bygg og deploy:

cd ~/synops/maskinrommet && cargo build --release
sudo systemctl restart maskinrommet

Faser

• Fase A (MVP): Chat-agent — implementert og verifisert
• Fase B: Autorisasjon og oppgaver (direct vs propose flyt)
• Fase C: Autonom implementering (claude Code som subprocess for kode-endringer)
• Fase D: @mentions, typing-indikator, admin-panel