# 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.

## 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.

```rust
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
├── core/           — agent-loop, tool dispatch, kontekst
├── providers/      — API-adaptere (anthropic, openai, gemini, ollama)
├── tools/          — verktøy-implementasjoner
├── tasklist/       — parser og kjører markdown-checklister
├── daemon/         — bakgrunnsprosess, filovervåking, intervall
├── recovery/       — checkpoint, gjenoppretting, kontekstkomprimering
└── synops/         — grafintegrasjon via synops-common
```

Bygget som lib + CLI. Lib kan embeddes i maskinrommet for
tettere integrasjon uten prosess-overhead.

## API-abstraksjon

Rust-traits for leverandør-uavhengighet:

```rust
#[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](https://www.rig.rs/)
- [AutoAgents — multi-agent i Rust](https://github.com/liquidos-ai/AutoAgents)
- [OpenCode — open source Claude Code-alternativ](https://opencode.ai/docs/agents/)
- [OpenCode konteksthåndtering](https://deepwiki.com/sst/opencode/2.4-context-management-and-compaction)
- [OpenDev — terminal-native coding agents](https://co-r-e.com/method/opendev-terminal-coding-agent)
- [Agent Harness arkitektur (2026)](https://dev.to/htekdev/agent-harnesses-why-2026-isnt-about-more-agents-its-about-controlling-them-1f24)
- [AI Coding Agents for the Terminal (paper)](https://arxiv.org/html/2603.05344v1)
- [Anthropic: Building Effective Agents](https://www.anthropic.com/research/building-effective-agents)
- [Claude Agent SDK](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)
- [Benchmarking AI Agent Frameworks 2026](https://dev.to/saivishwak/benchmarking-ai-agent-frameworks-in-2026-autoagents-rust-vs-langchain-langgraph-llamaindex-338f)

### 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.