vegard/synops
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

synops-agent proposal: research og supersett-ambisjon

Browse source 
Oppdatert med research fra mars 2026:
- Rig.rs som provider-abstraksjon (24% CPU, <1.1GB vs Python >4.7GB)
- OpenCode Extended ReAct Loop (tenke + selvkritikk + handling)
- Adaptive Context Compaction (ACC) for kontekstvindu
- Harness-mønsteret (kontrollplan mellom LLM og verktøy)
- Worktree-isolasjon for sub-agenter
- MCP-støtte som industristandard
Supersett av Claude Code: daemon-modus, innebygd oppgavestyring,
selvovervåking, sub-agenter med valgfri modell per agent.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
vegard 2026-03-19 07:32:41 +00:00
parent c2fb8555cc
commit 2bdbff5ee8
1 changed files with 267 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

320
docs/proposals/agent_harness.md
View file

@ -1,76 +1,290 @@
# Proposal: synops-agent — modell-agnostisk agent-harness i Rust # Proposal: synops-agent — modell-agnostisk agent-runtime i Rust
## Problemstilling ## Ambisjon
Claude Code er kraftig, men bundet til Anthropic-modeller. Vi ønsker Ikke en kopi av Claude Code. Et **superset**. Modell-agnostisk,
samme type agent-loop (tool use → execute → loop) med valgfri modell selvovervåkende, med innebygd oppgavestyring og prosesshåndtering.
(Grok, Gemini, OpenRouter, lokale modeller via Ollama). Claude Code er en utmerket interaktiv assistent — synops-agent er
en autonom arbeider som kan kjøre i dager uten tilsyn.
## Konsept ## Hva Claude Code gjør bra (og vi beholder)
Et Rust CLI-verktøy som implementerer en agent-loop med verktøy. - Tool-loop (prompt → tool_calls → execute → loop)
Bruker LiteLLM (allerede i stacken) for API-oversettelse, eller - Fil-operasjoner (read, edit, write, grep, glob)
snakker direkte med leverandør-APIer. - 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 ## Arkitektur
``` ```
synops-agent --model grok-3 --prompt "fiks buggen i auth.ts" synops-agent
│ ├── core/ — agent-loop, tool dispatch, kontekst
├── Sender prompt + tool-definisjoner til LLM ├── providers/ — API-adaptere (anthropic, openai, gemini, ollama)
├── LLM svarer med tool_calls ├── tools/ — verktøy-implementasjoner
├── Agent kjører verktøy (Read, Edit, Bash, etc.) ├── tasklist/ — parser og kjører markdown-checklister
├── Sender verktøy-resultater tilbake ├── daemon/ — bakgrunnsprosess, filovervåking, intervall
└── Loop til LLM svarer uten tool_calls ├── recovery/ — checkpoint, gjenoppretting, kontekstkomprimering
└── synops/ — grafintegrasjon via synops-common
``` ```
## Verktøy (subset av Claude Code) Bygget som lib + CLI. Lib kan embeddes i maskinrommet for
tettere integrasjon uten prosess-overhead.
| 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 ## API-abstraksjon
Alle store LLM-APIer støtter function calling / tool use, men med Rust-traits for leverandør-uavhengighet:
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 ```rust
i Rust for lavere latens og færre avhengigheter. #[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)
}
```
## Integrasjon med Synops Implementasjoner for:
- Anthropic (direkte, for beste tool_use-støtte)
- Maskinrommet kan spawne `synops-agent` som en jobb - OpenAI-kompatibelt (Grok, OpenRouter, vLLM, Ollama)
- Deler verktøykasse med andre CLI-verktøy (synops-common) - Gemini (direkte, for grounding og lange kontekster)
- Kan bruke `ai_job_routing` for å velge modell per kontekst - LiteLLM (fallback — dekker alt, men med overhead)
- Logger i `ai_usage_log` som alle andre AI-kall
- Kan erstatte `synops-respond` for chat-svar med valgfri modell
## Differensiatorer vs Claude Code ## Differensiatorer vs Claude Code
- Modell-agnostisk (hele poenget) | | Claude Code | synops-agent |
- Kan kjøres headless / i jobbkø (ikke interaktiv) |---|---|---|
- Integrert med Synops sin graf (kan bruke synops-search, synops-node etc.) | Modeller | Kun Anthropic | Alle |
- Enklere verktøysett (ikke IDE-integrasjon, bare fil+shell) | Modus | Interaktiv | Interaktiv + autonom + daemon |
- Rust = rask oppstart, lav ressursbruk | 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) |
## Åpne spørsmål ## Hva dette erstatter
- Streaming vs batch? (Streaming gir bedre UX i chat, batch er enklere) - `run-next-task.sh` og lignende shell-scripts
- Maks iterasjoner / kostnadsstopp? - Manuelle looper for å holde prosesser i gang
- Kontekstvindu-håndtering for store kodebaser? - Ad-hoc cron-jobber for agentoppgaver
- Skal det være en lib (synops-agent-core) + CLI (synops-agent)? - `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.
## Prioritet ## Prioritet
Ikke hasteoppgave. Bygges når vi har behov for multi-modell agent-loop, Middels-høy. Erstatter fragil infrastruktur (shell-scripts, looper)
f.eks. for billigere batch-jobber (Gemini Flash) eller spesialiserte med noe robust. Kan bygges inkrementelt — fase 1 er allerede nyttig.
modeller (Grok for sanntidsinformasjon). Rig som avhengighet reduserer scope for fase 1-2 betydelig.