synops/docs/proposals/agent_harness.md

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

Ambisjon

En erstatning for Claude Code. Ikke en hjelper, ikke en wrapper — et selvstendig, fullverdig alternativ som kan gjøre alt Claude Code gjør, men med valgfri modell og mer funksjonalitet.

Claude Code brukes til å utvikle og teste synops-agent. Målet er at synops-agent kan ta over hele arbeidsflyten: interaktiv utvikling, autonome oppgaver, daemon-drift. Med hvilken som helst modell.

Hvorfor ikke Claude Code som tjeneste?

Vi har vurdert å bruke Claude Code direkte for AI-tjenester i Synops (chat-svar, orkestrering, bakgrunnsjobber). Det er ikke egnet:

• Lang instansieringstid — sekunder til oppstart per invokasjon
• Høy minnebruk — hundrevis av MB per instans, skalerer ikke
• Ingen API — kun terminal-grensesnitt, ikke programmerbart
• Låst til Anthropic — kan ikke bruke billigere/raskere modeller
• Ikke designet for embedding — ment som interaktivt utviklerverktøy

synops-agent løser alle disse:

• Rask oppstart — Rust binary, millisekunder
• Lavt minnebruk — Rust, ingen runtime overhead
• API og CLI — lib (embed i maskinrommet) + CLI (standalone)
• Modell-agnostisk — velg riktig modell per oppgave
• Designet for embedding — kan kjøre som HTTP-endepunkt, jobbkø-worker, eller daemon

Bruksområder i Synops

synops-agent erstatter dagens claude -p invokasjon i maskinrommet og åpner for nye muligheter:

Bruk	I dag	Med synops-agent
Chat-svar (@bot)	claude -p (tregt, dyrt)	Inline, rask, valgfri modell
Orkestrering	Shell-scripts + claude -p	Native agent-loop
Transkripsjons-oppsummering	synops-summarize → LiteLLM	Agent med kontekst
Kode-generering	Claude Code (manuelt)	Autonom med tasklist
Bakgrunnsjobber	Jobbkø → CLI-verktøy	Agent som jobbkø-worker
Bruker-chat i appen	Ikke mulig (for tregt)	Sub-sekund responstid

Hva Claude Code gjør bra (og vi beholder)

• Tool-loop (prompt → tool_calls → execute → loop)
• Fil-operasjoner (read, edit, write, grep, glob)
• Shell-tilgang (bash)
• Plan-modus (tenk før du handler)
• Kontekstbevissthet (CLAUDE.md, prosjektstruktur)

Hva vi gjør i tillegg (supersett)

1. Modell-agnostisk

Bruk hvilken som helst modell: Anthropic, Grok, Gemini, OpenRouter, Ollama, lokale modeller. Velg per oppgave, per steg, per budsjett.

synops-agent --model gemini-flash --task "oppdater alle TODO-kommentarer"
synops-agent --model grok-3 --task "research denne teknologien"
synops-agent --model claude-opus --task "redesign auth-systemet"

Modellvalg kan også være dynamisk: start med billig modell, eskaler til dyrere ved feil (allerede et mønster i orkestreringen).

2. Innebygd oppgavestyring

Ikke avhengig av eksterne scripts eller looper. Agenten eier sin egen arbeidsliste og kjører oppgaver sekvensielt eller parallelt.

synops-agent --tasklist tasks.md
synops-agent --tasklist "docs/fikseliste.md" --filter "[ ]"

• Parser markdown-checklister (som tasks.md)
• Plukker neste ugjorte oppgave
• Markerer pågående, ferdig, feilet
• Committer og pusher per oppgave
• Gjenopptar etter krasj (leser tasklist, finner hvor den var)

3. Selvovervåking og gjenoppretting

Prosessen holder seg selv i live. Ingen externe watchdogs nødvendig.

• Heartbeat: Skriver tidsstempel til en fil. Annen instans kan sjekke om agenten er aktiv.
• Timeout-deteksjon: Oppdager om en tool-call henger (f.eks. bash som venter på input) og dreper den.
• Kostnadstak: Stopper ved budsjettgrense per oppgave/sesjon. Rapporterer gjenstående arbeid.
• Kontekstvindu-håndtering: Komprimerer historikk automatisk når konteksten nærmer seg grensen. Oppsummerer tidligere steg.
• Feilgjenoppretting: Ved API-feil, retry med backoff. Ved gjentatte feil, eskaler modell eller rapporter og gå videre.

4. Prosesshåndtering (erstatter shell-scripts)

Innebygd daemon-modus som erstatter ad-hoc looper og cron.

synops-agent daemon --tasklist tasks.md --interval 5m
synops-agent daemon --watch "docs/fikseliste.md" --on-change run

• Daemon-modus: Kjør som bakgrunnsprosess, plukk oppgaver
• Filovervåking: Reager på endringer i arbeidslister
• Intervall: Poll med konfigurerbart intervall
• Signalhåndtering: SIGTERM → fullfør nåværende oppgave → avslutt
• Pid-fil + lockfil: Forhindre dobbeltstart, tillat status-sjekk

5. Utvidet verktøykasse

Alt Claude Code har, pluss:

Verktøy	Funksjon
read_file	Les fil (med offset/limit, PDF, bilder, notebooks)
write_file	Skriv fil
edit_file	Finn-og-erstatt (unik match, replace_all)
bash	Kjør shell-kommando (med timeout, bakgrunn)
grep	Søk i filer (ripgrep, regex, multiline)
glob	Finn filer etter mønster
web_fetch	Hent URL (HTML → tekst, JSON-parsing)
web_search	Søk på nett
synops_search	Søk i Synops-grafen
synops_node	Les/skriv noder og edges
synops_create	Opprett noder, edges, kommunikasjoner
spawn_agent	Start sub-agent med eget oppdrag og modell
notify	Send varsel (epost, WebSocket, chat)
schedule	Planlegg fremtidig kjøring
checkpoint	Lagre mellomtilstand for gjenoppretting

6. Sub-agenter

Kan spawne sub-agenter for parallelt arbeid, akkurat som Claude Code sin Agent-tool, men med valgfri modell per sub-agent.

spawn_agent({
    model: "gemini-flash",
    prompt: "søk etter alle steder som bruker denne funksjonen",
    tools: ["grep", "glob", "read_file"],
    max_cost: 0.10,
})

7. Grafintegrasjon (Synops-spesifikt)

Agenten er en førsteklasses borger i Synops:

• Har en agent-node i grafen
• Kan lese/skrive noder og edges
• Kan delta i kommunikasjonsnoder (chat)
• Logger all aktivitet i grafen
• Orkestreringer kan spawne agenten
• Kan trigges av graf-events (ny node, ny edge)

Arkitektur

synops-agent (workspace crate)
├── synops-agent-core/   — lib: agent-loop, tool dispatch, kontekst
│   ├── providers/       — API-adaptere (anthropic, openai, gemini, ollama)
│   ├── tools/           — verktøy-implementasjoner
│   ├── context/         — kontekstvindu, ACC, oppsummering
│   ├── tasklist/        — parser og kjører markdown-checklister
│   └── budget/          — token-regnskap, kostnadsovervåking
├── synops-agent-cli/    — CLI-binary: interaktiv + batch + daemon
└── synops-agent-api/    — HTTP-server: embed i maskinrommet eller standalone

Tre bruksmåter:

1. Lib (synops-agent-core) — embed direkte i maskinrommet. Ingen prosess-overhead. Chat-svar på millisekunder.
2. CLI (synops-agent) — interaktiv terminal, tasklist-runner, daemon-modus. Erstatter Claude Code for utvikling.
3. API (synops-agent-api) — HTTP-endepunkt for appen. Maskinrommet kaller det i stedet for claude -p. Kan også kjøres standalone som mikrotjeneste.

API-abstraksjon

Rust-traits for leverandør-uavhengighet:

#[async_trait]
trait LlmProvider {
    async fn complete(&self, messages: &[Message], tools: &[Tool]) -> Result<Response>;
    fn supports_streaming(&self) -> bool;
    fn model_id(&self) -> &str;
    fn cost_per_token(&self) -> (f64, f64); // (input, output)
}

Implementasjoner for:

• Anthropic (direkte, for beste tool_use-støtte)
• OpenAI-kompatibelt (Grok, OpenRouter, vLLM, Ollama)
• Gemini (direkte, for grounding og lange kontekster)
• LiteLLM (fallback — dekker alt, men med overhead)

Differensiatorer vs Claude Code

	Claude Code	synops-agent
Modeller	Kun Anthropic	Alle (Anthropic, Grok, Gemini, Ollama, ...)
Modus	Interaktiv	Interaktiv + autonom + daemon
Oppgavestyring	Manuelt	Innebygd tasklist-parser
Gjenoppretting	Manuelt	Automatisk checkpoint + resume
Sub-agenter	Samme modell	Valgfri modell per agent
Prosesshåndtering	Ingen	Daemon, watchdog, signaler
Grafintegrasjon	Filbasert	Native node/edge-tilgang
Kostnadsovervåking	Begrenset	Sanntids token-regnskap per modell
Eskalering	Ingen	Auto-eskaler billig → middels → smart
Verifikasjon	Manuelt	Innebygd utfør/verifiser-loop
Implementasjon	Node.js (lukket)	Rust (vår, åpen, rask)
Avhengighet	Anthropic-abonnement	Valgfri leverandør, inkl. gratis/lokal

Hva dette erstatter

• run-next-task.sh og lignende shell-scripts
• Manuelle looper for å holde prosesser i gang
• Ad-hoc cron-jobber for agentoppgaver
• synops-respond (kan bli en modus i synops-agent)
• Deler av orkestreringens executor

Faser

1. Core loop + fil-verktøy: Agent-loop som kan lese, skrive, kjøre bash. Én provider (OpenAI-kompatibelt via LiteLLM).
2. Flere providers: Anthropic direkte, Gemini, Ollama.
3. Tasklist-parser: Les markdown-checklister, kjør oppgaver.
4. Daemon-modus: Bakgrunnsprosess med intervall/filovervåking.
5. Sub-agenter: Spawn med valgfri modell.
6. Grafintegrasjon: synops-common for node/edge-tilgang.
7. Checkpoint/recovery: Lagre og gjenoppta tilstand.

Research: eksisterende løsninger og mønstre (mars 2026)

Rust-rammeverk

Rig (rig.rs) — det mest modne Rust LLM-rammeverket. Trait-basert arkitektur med CompletionModel og EmbeddingModel traits. Agent-type som kombinerer modell + systemprompt + verktøy + kontekstdokumenter. I 2026-benchmarks: 24.3% CPU (lavest), <1.1 GB minne (Python >4.7 GB). Relevant for vår provider-abstraksjon.

AutoAgents (liquidos-ai) — multi-agent framework i Rust med type-safe agent-modell, strukturert tool calling, pluggbare backends. God referanse for sub-agent-spawning.

Åpen kildekode Claude Code-alternativer

OpenCode — den sterkeste open source-konkurrenten. Støtter 75+ LLM-providers. Nøkkelarkitektur: separasjon mellom agent-oppførsel og modellvalg. Agent eier planlegging/verktøy, bruker velger modell. Extended ReAct Loop med fire faser per tur:

1. Automatisk kontekstkomprimering når token-budsjettet nærmer seg
2. Valgfri tenke-fase for pre-action reasoning
3. Valgfri selvkritikk-fase
4. Standard Reason-Act-Execute-Observe

Cline — 5M+ installasjoner. Har native sub-agenter for parallell utføring og headless CLI-modus for CI/CD.

Goose (Block) — CLI-first, DevOps-fokusert, gratis.

OpenHands — autonome koding-agenter på plattformnivå.

Arkitekturmønstre vi bør adoptere

Harness-mønsteret — harnessen er kontrollplanet som wrapper agentens utføring. Sitter mellom LLM og omverdenen. Styrer livssyklus, kontekstvindu, verktøytilgang og sikkerhetsgrenser. Modellen tar faglige beslutninger, harnessen tar operasjonelle beslutninger.

Adaptive Context Compaction (ACC) fra OpenCode/OpenDev:

• 70% kapasitet: logging og trendovervåking
• 80%: erstatt eldre verktøy-output med kompakte referansepekere
• 90%: aggressiv oppsummering av historikk
• Bruker prompt_tokens fra API-respons som kalibreringsanker

ToolRegistry-mønster: Sentralt register som dispatcher kall til typede handlers. Støtter batch parallell utføring og on-demand MCP tool discovery.

Worktree-isolasjon fra Claude Agent SDK: distribuer arbeid til sub-agenter i isolerte git worktrees, eliminer redigerings-kollisjoner. Hvert oppdrag får sin egen branch.

Skills-system: Organiserte mapper med instruksjoner, scripts og ressurser som agenter oppdager og laster dynamisk.

Designprinsipper fra Anthropic

• Hold agentdesignet enkelt — de mest vellykkede implementasjonene bruker enkle, komponerbare mønstre fremfor komplekse rammeverk
• MCP (Model Context Protocol) som standard for verktøy-integrasjon
• Agenten er runtime-motoren — SDK-er delegerer til den, ikke omvendt

Referanser

• Rig — Rust LLM framework
• AutoAgents — multi-agent i Rust
• OpenCode — open source Claude Code-alternativ
• OpenCode konteksthåndtering
• OpenDev — terminal-native coding agents
• Agent Harness arkitektur (2026)
• AI Coding Agents for the Terminal (paper)
• Anthropic: Building Effective Agents
• Claude Agent SDK
• Benchmarking AI Agent Frameworks 2026

Implikasjoner for synops-agent

1. Bruk Rig som utgangspunkt for provider-abstraksjon — ikke skriv fra scratch. Rig sine traits er veldesignet og battle-tested.
2. Implementer ACC for kontekstvindu — dette er state of the art.
3. Extended ReAct Loop med tenke- og selvkritikk-fase, ikke bare enkel tool-loop.
4. ToolRegistry med parallell dispatch — ikke sekvensiell.
5. MCP-støtte fra dag 1 — industristandarder er viktigere enn egne protokoller.
6. Worktree-isolasjon for sub-agenter som redigerer kode.
7. Enkel arkitektur — Anthropic har rett: komponerbare patterns slår komplekse frameworks.

Orkestreringsmodell: smart leder, billige arbeidere

Selvstendig orkestrator

synops-agent er sin egen orkestrator. Den velger modell per oppgave, delegerer til sub-agenter, eskalerer ved feil — uten ekstern styring.

synops-agent --tasklist fikseliste.md --orchestrator opus --worker flash
synops-agent --task "redesign auth-systemet" --model sonnet
synops-agent daemon --watch tasks.md --orchestrator sonnet --worker haiku

I tillegg er den et CLI-verktøy som kan kalles fra Claude Code for å eksperimentere med modellkombinasjoner og finne hva som fungerer best for ulike oppgavetyper. Men det er utvikling og testing — ikke den tiltenkte driftsmodellen.

Tre intelligensnivåer

┌─────────────────────────────────────────────┐
│  ORKESTRATOR (Claude Opus / Sonnet)         │
│  Planlegger, arkitekturbeslutninger,        │
│  kvalitetsvurdering, strategi               │
├─────────────────────────────────────────────┤
│  MIDDELS (Sonnet / Grok / Gemini Pro)       │
│  Implementering, refaktorering,             │
│  code review, feilsøking                    │
├─────────────────────────────────────────────┤
│  BILLIG (Haiku / Flash / Grok Mini)         │
│  Søk, grep, oppsummering, formatering,      │
│  enhetstester, dokumentasjon, triage        │
└─────────────────────────────────────────────┘

Orkestratoren (Claude Code eller synops-agent med smart modell) bestemmer hvilket nivå hver deloppgave krever. Hvert nivå kan ha sin egen agent-loop med fulle verktøy.

Utfør billig, verifiser smart

Kjernestrategi for kostnadseffektiv kvalitet:

1. Orkestrator bryter ned oppgaven i steg
2. Billig modell utfører hvert steg (kode, søk, etc.)
3. Smart modell verifiserer resultatet
4. Ved feil: eskaler til middels/smart for retry
5. Ved gjentatt feil: orkestrator tar over selv

Eksempel — fiks 10 TODO-er i kodebasen:

Orkestrator (Opus): "Her er 10 TODO-er, fiks dem én om gangen"
  → Agent (Flash): fikser TODO #1, committer
  → Orkestrator (Opus): review diff — "OK, neste"
  → Agent (Flash): fikser TODO #2, committer
  → Orkestrator (Opus): review diff — "Feil. La meg forklare..."
  → Agent (Sonnet): fikser TODO #2 med bedre kontekst
  → Orkestrator (Opus): review diff — "Bra, neste"

Kostnad: ~90% av arbeidet på billigste modell, ~8% på middels, ~2% på dyreste. Kvaliteten til dyreste modell.

Automatisk modellvalg

synops-agent kan velge modell basert på oppgavens karakter:

Signal	Nivå	Modell
--task "søk etter..."	Billig	Flash/Mini
--task "implementer..."	Middels	Sonnet/Pro
--task "design..."	Smart	Opus
Feilet med billig	Eskaler	Middels → Smart
--verify flagg	Smart	Opus (kun review)
--budget 0.10	Auto	Billigst mulig

Maskinrommets ai_job_routing-tabell kan styre default-mappingen.

synops-agent som fullverdig arbeidsflyt

Vegard (interaktiv)
  │
  └── synops-agent --tasklist fikseliste.md
        │  orchestrator: opus
        │  worker: flash
        │  verifier: sonnet
        │
        ├── Bug 1 → worker (flash) → verifier (sonnet) ✓ → commit
        ├── Bug 2 → worker (flash) → verifier (sonnet) ✗
        │            → eskaler → worker (sonnet) → verifier (opus) ✓
        ├── Bug 3 → worker (flash) → verifier (sonnet) ✓ → commit
        │
        ├── "Trenger research" → sub-agent (grok-3, sanntidsinfo)
        │
        └── Ferdig. 3/3 bugs fikset. $0.22 brukt.

Samme arbeidsflyt som Claude Code, men:

• Valgfri modell på hvert nivå
• Automatisk eskalering ved feil
• Innebygd tasklist-parser
• Kjører uten tilsyn (daemon-modus)
• Tilgang til modeller Claude Code ikke har (Grok for sanntid, Gemini for lange kontekster, lokale modeller for sensitive data)

Token-regnskap

Harnessen teller og akkumulerer token counts per modell gjennom hele kjøringen. Ikke bare logging i etterkant — sanntids regnskap som brukes til aktive beslutninger.

┌────────────────────────────────────────────────┐
│ synops-agent sesjon #4721                      │
│ Oppgave: "Fiks 10 TODO-er i kodebasen"        │
│                                                │
│ Modell           Input    Output    Kostnad    │
│ gemini-flash     284k     12k       $0.02      │
│ claude-sonnet    18k      4k        $0.08      │
│ claude-opus      3k       1k        $0.12      │
│ ────────────────────────────────────────────── │
│ Totalt           305k     17k       $0.22      │
│ Budsjett brukt: 22% av $1.00                   │
└────────────────────────────────────────────────┘

Implementasjon:

• Hvert API-kall returnerer usage.input_tokens og usage.output_tokens
• Harnessen akkumulerer per modell i en HashMap<String, TokenUsage>
• Kostnad beregnes fra modellens pris per token (konfigurerbar tabell)
• Tilgjengelig for orkestratoren via --stats eller som verktøy-output
• Ved budsjettgrense: stopp, rapporter gjenstående, foreslå billigere modell
• Skrives til ai_usage_log i PG ved sesjonsslutt (og ved checkpoint)

Bruksområder for sanntids token-regnskap:

• Budsjettovervåking: Stopp før kostnadssprekk
• Modellvalg: "Flash har brukt 200k tokens uten resultat — eskaler"
• Effektivitetsmåling: Tokens per fullført oppgave per modell
• Rapportering: Vegard ser daglig/ukentlig forbruk per modellnivå
• Orkestrator-input: Claude Code kan lese stats og justere strategi

Eksperimentering med modellvalg

synops-agent logger modell, oppgavetype, kostnad, tid og resultat (suksess/feil/eskalert) i ai_usage_log. Over tid bygges data som viser:

• Hvilke modeller som er best per oppgavetype
• Kostnadsoptimal eskaleringsterskel
• Modeller som feiler oftere på spesifikke oppgaver
• ROI for verify-steg (fanger det faktisk feil?)

Claude Code kan analysere denne dataen og justere strategi: "Gemini Flash feiler på 40% av refaktoreringsjobber — bruk Sonnet for de fra nå av, men behold Flash for søk og dokumentasjon."

Prioritet

Middels-høy. Erstatter fragil infrastruktur (shell-scripts, looper) med noe robust. Kan bygges inkrementelt — fase 1 er allerede nyttig. Rig som avhengighet reduserer scope for fase 1-2 betydelig. Orkestrerings-mønsteret gir umiddelbar verdi: Claude Code kan delegere til billige modeller fra dag 1 av fase 1.