synops/docs/proposals/agent_harness.md

Proposal: synops-agent — modell-agnostisk agent-harness i Rust

Problemstilling

Claude Code er kraftig, men bundet til Anthropic-modeller. Vi ønsker samme type agent-loop (tool use → execute → loop) med valgfri modell (Grok, Gemini, OpenRouter, lokale modeller via Ollama).

Konsept

Et Rust CLI-verktøy som implementerer en agent-loop med verktøy. Bruker LiteLLM (allerede i stacken) for API-oversettelse, eller snakker direkte med leverandør-APIer.

Arkitektur

synops-agent --model grok-3 --prompt "fiks buggen i auth.ts"
    │
    ├── Sender prompt + tool-definisjoner til LLM
    ├── LLM svarer med tool_calls
    ├── Agent kjører verktøy (Read, Edit, Bash, etc.)
    ├── Sender verktøy-resultater tilbake
    └── Loop til LLM svarer uten tool_calls

Verktøy (subset av Claude Code)

Verktøy	Funksjon
read_file	Les fil (med offset/limit)
write_file	Skriv fil
edit_file	Finn-og-erstatt i fil
bash	Kjør shell-kommando
grep	Søk i filer (ripgrep)
glob	Finn filer etter mønster

API-abstraksjon

Alle store LLM-APIer støtter function calling / tool use, men med ulike formater:

• OpenAI-kompatibelt (Grok, OpenRouter, lokale): tools[] med function schema
• Gemini: functionDeclarations i tools[]
• Anthropic: tools[] med input_schema

LiteLLM oversetter mellom disse, men vi kan også gjøre det direkte i Rust for lavere latens og færre avhengigheter.

Integrasjon med Synops

• Maskinrommet kan spawne synops-agent som en jobb
• Deler verktøykasse med andre CLI-verktøy (synops-common)
• Kan bruke ai_job_routing for å velge modell per kontekst
• Logger i ai_usage_log som alle andre AI-kall
• Kan erstatte synops-respond for chat-svar med valgfri modell

Differensiatorer vs Claude Code

• Modell-agnostisk (hele poenget)
• Kan kjøres headless / i jobbkø (ikke interaktiv)
• Integrert med Synops sin graf (kan bruke synops-search, synops-node etc.)
• Enklere verktøysett (ikke IDE-integrasjon, bare fil+shell)
• Rust = rask oppstart, lav ressursbruk

Åpne spørsmål

• Streaming vs batch? (Streaming gir bedre UX i chat, batch er enklere)
• Maks iterasjoner / kostnadsstopp?
• Kontekstvindu-håndtering for store kodebaser?
• Skal det være en lib (synops-agent-core) + CLI (synops-agent)?

Prioritet

Ikke hasteoppgave. Bygges når vi har behov for multi-modell agent-loop, f.eks. for billigere batch-jobber (Gemini Flash) eller spesialiserte modeller (Grok for sanntidsinformasjon).