From 2bdbff5ee84665d15861197ea100f32e23631aa6 Mon Sep 17 00:00:00 2001 From: vegard Date: Thu, 19 Mar 2026 07:32:41 +0000 Subject: [PATCH] synops-agent proposal: research og supersett-ambisjon MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- docs/proposals/agent_harness.md | 320 ++++++++++++++++++++++++++------ 1 file changed, 267 insertions(+), 53 deletions(-) diff --git a/docs/proposals/agent_harness.md b/docs/proposals/agent_harness.md index 559b2f7..4627b5e 100644 --- a/docs/proposals/agent_harness.md +++ b/docs/proposals/agent_harness.md @@ -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 -samme type agent-loop (tool use → execute → loop) med valgfri modell -(Grok, Gemini, OpenRouter, lokale modeller via Ollama). +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. -## Konsept +## Hva Claude Code gjør bra (og vi beholder) -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. +- 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 --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 +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 ``` -## 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 | +Bygget som lib + CLI. Lib kan embeddes i maskinrommet for +tettere integrasjon uten prosess-overhead. ## 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` +Rust-traits for leverandør-uavhengighet: -LiteLLM oversetter mellom disse, men vi kan også gjøre det direkte -i Rust for lavere latens og færre avhengigheter. +```rust +#[async_trait] +trait LlmProvider { + async fn complete(&self, messages: &[Message], tools: &[Tool]) -> Result; + fn supports_streaming(&self) -> bool; + fn model_id(&self) -> &str; + fn cost_per_token(&self) -> (f64, f64); // (input, output) +} +``` -## 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 +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 -- 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 +| | 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) | -## Åpne spørsmål +## Hva dette erstatter -- 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)? +- `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. ## 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). +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.