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

## Ambisjon

Ikke en kopi av Claude Code. Et **superset**. Modell-agnostisk,
selvovervåkende, med innebygd oppgavestyring og prosesshåndtering.
Claude Code er en utmerket interaktiv assistent — synops-agent er
en autonom arbeider som kan kjøre i dager uten tilsyn.

## 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 |
| 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 | Ingen | Per-oppgave budsjett |
| Implementasjon | Node.js (lukket) | Rust (vår, åpen) |

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

### Kjørbar fra Claude Code

synops-agent er et CLI-verktøy. Claude Code kan kalle det via Bash.
Det betyr at Claude Code (dyr, smart) kan delegere arbeid til billige
modeller uten å bruke egne tokens:

```
# Claude Code kjører dette:
synops-agent --model gemini-flash --task "finn alle filer som importerer auth.ts"
synops-agent --model grok-3-mini --task "skriv enhetstester for denne funksjonen"
synops-agent --model claude-haiku --task "oppsummer disse 40 filene"
```

Claude Code beholder det store bildet. synops-agent gjør gruntarbeidet.

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

### Claude Code som super-orkestrator

Det ultimate mønsteret:

```
Claude Code (interaktiv med Vegard)
  │
  ├── "Fiks alle bugs i fikseliste.md"
  │     └── synops-agent --model sonnet --tasklist fikseliste.md
  │           ├── Bug 1 → agent (flash) → verifiser (sonnet) ✓
  │           ├── Bug 2 → agent (flash) → verifiser (sonnet) ✗
  │           │            → eskaler → agent (sonnet) → verifiser ✓
  │           └── Bug 3 → agent (flash) → verifiser (sonnet) ✓
  │
  ├── "Research denne teknologien"
  │     └── synops-agent --model grok-3 --task "..." (sanntidsinfo)
  │
  └── "Optimaliser databasespørringene"
        └── synops-agent --model gemini-pro --task "..."
             └── Sub-agent (flash): "profiler denne spørringen"
```

Claude Code bruker sin kontekst til å forstå hva som trengs,
delegerer utføringen, og bruker resultatet. Billigere, raskere,
og med tilgang til modeller Claude Code ikke har (Grok for
sanntid, Gemini for lange kontekster, lokale modeller for
sensitive data).

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