chris/OSVauco
1
0
Fork 0
Code Issues 1 Pull Requests Actions 2 Packages Projects Releases Wiki Activity
feat/emma-operator-poc
OSVauco/docs/HANDOFF.md

19 KiB
Raw Permalink Blame History

HANDOFF — Vauco OS

Sist oppdatert: 2026-06-29 20:42 CEST Skrevet av: Perplexity (for Chris Christiansen) Status: Fase D — VM oppgradert, Gitea som primær, Ollama neste

REPO TRUTH AND BACKUP STATUS (2026-07-16)

  • Gitea is the authoritative source of truth for OSVauco.
  • Main was successfully pushed to Gitea and is now aligned at commit e2f4339154.
  • GitHub is not part of the active automation path.
  • GitHub is only an optional manual backup mirror.
  • The current Gitea post-receive hook for GitHub mirroring is non-blocking and may fail without affecting the authoritative Gitea repo.
  • Do not rely on GitHub mirror status for operational truth.
  • If backup is needed later, it can be done manually after the primary Gitea path is stable.

Gitea + OPAX-MCP status (2026-07-07)

  • Gitea er migrert til CPU-VM gitea-cpu-vm og svarer på http://34.170.51.84:3000 og /api/v1/version.
  • OSVauco-repoet på dev-VM har remotes:
    • origin + gitea: http://34.170.51.84:3000/chris/OSVauco.git.
  • Alle tidligere hardkodede Gitea-IP-er er oppdatert til CPU-VM:
    • opax-mcp/server.py (GITEA_URL default),
    • emma/emma_gitea.py (Emma-klient),
    • .gemini/GEMINI.md (PRIMARY_GIT, testkommandoer),
    • dev-start.sh (GITEA_REMOTE).
  • Ny opax-mcp/gitea_handler.py er lagt til og bruker GITEA_URL/GITEA_TOKEN fra env for Gitea-API-kall.
  • Neste steg (ikke utført ennå):
    • Verifisere GITEA_TOKEN via gcloud secrets versions access --secret=gitea-token,
    • kjøre enkel curl mot "$GITEA_URL/api/v1/version" med token,
    • deretter koble OPAX-MCP/Gitea-tools til den nye instansen.

Dette dokumentet er oppdatert til å reflektere at Gitea på CPU-VM er ny primær Git-master; GitHub er fortsatt kun legacy/backup.

⚠️ KRITISKE REGLER — les alltid først

  • Hovedapp: main.py i rot — IKKJE agents/core-logic/app.py
  • Dockerfile: agents/core-logic/Dockerfile — WORKDIR /app, CMD uvicorn main:app
  • Region: us-central1 | Service: osvauco-agent | Prosjekt: propane-will-491900-m5
  • ALDRI --audiences-flag med gcloud auth print-identity-token — det er for service accounts, ikke user accounts
  • IAP identity token: hentes fra GCE metadata server, IKKE fra gcloud CLI
  • Primær Git: http://34.170.51.84:3000/chris/OSVauco — Gitea er nå kilde, GitHub er kun backup.
  • git remote: origin = Gitea. GitHub-remote er fjernet.
  • Emma rapporterer til: Chris Christiansen chris.christiansen@vauco.no — ingen andre kan gi GO
  • emma_runner.py finnes IKKE — riktig fil er emma/emma_run.py
  • Ollama: IKKE installert ennå — neste oppgave

📈 STRATEGISK FASEPLAN: Gitea som Source of Truth

Status: Planlagt

Arkitekturbeslutning (Låst)

  • Gitea: Eneste "Source of Truth" for all kode.
  • OPAX-MCP: Eneste eksterne agent-gateway (over HTTPS).
  • GitHub: Kun en potensiell passiv backup/mirror, ikke i operativ flyt.

Domene-rollemodell (Låst)

  • git.vauco.no → Gitea: Source of truth for kode.
  • opax.vauco.no → OPAX-MCP: Ekstern agent-gateway.
  • ops.vauco.no → Parkert: Droppes inntil videre for å redusere kompleksitet.

Fase 1: Stabiliser opax-mcp konfigurasjon

  • Beslutning (Låst): Alternativ B er valgt. opax-mcp.yaml blir eneste autoritative kilde til sannhet for deploy-konfigurasjon.
  • Filer/Tjenester: opax-mcp.yaml, cloudbuild.mcp.yaml, Cloud Run opax-mcp.
  • Verifisering: gcloud run services describe opax-mcp viser korrekt konfigurasjon.

Fase 1 – TODO:

  • Mål: Én autoritativ deploy-kilde for opax-mcp (ikke manuell gcloud run deploy --source .).
  • Ferdig-kriterie: Live-opax-mcp bygges fra en definert pipeline som matcher opax-mcp.yaml (samme env-sett og image-vei).

Fase 2: Etablere Gitea-capability bak OPAX-MCP

  • Mål: Etablere Gitea-funksjonalitet bak gatewayen, med tydelig skille mellom repo/Gitea og CI/CD.
  • Filer/Tjenester: opax-mcp (som gateway), en ny/dedikert Gitea-agent service.
  • Verifisering: curl til opax-mcp ruter et Gitea-kall korrekt til backend-tjenesten og gir HTTP 200.
  • Ferdig-kriterie: Gitea-funksjonalitet er tilgjengelig via opax-mcp, implementert i en separat tjeneste.

Fase 2 – Gitea Capabilities (Scope):

Repo-lesing (Read-only):

  • list_repo_files: Viser filer og mapper i en gitt bane.
  • get_file_content: Henter innholdet i en spesifikk fil.
  • list_commits: Viser de siste commits for en branch.
  • list_open_issues: Viser åpne issues i repoet.

Repo-skriving (Operator-only):

  • update_file: Oppdaterer en eksisterende fil (erstatter push_file).
  • create_issue: Oppretter en ny issue.
  • create_branch: Oppretter en ny branch.
  • create_commit: Lager en ny commit med endringer.

Fase 2 – Implementasjonsretning (B-prime):

Blocker / Prerequisite for Implementasjon:

  • GITEA_URL og GITEA_REPO må legges til som autoritative miljøvariabler i opax-mcp.yaml før koding av Gitea-handleren starter.
  • Hardkodede fallback-verdier i server.py skal ikke lenger være kilde til sannhet for konfigurasjon.
  • Logikken i server.py kan fortsatt bruke mønsteret p.get('repo', GITEA_REPO) for fleksibilitet, men kun etter at GITEA_REPO er deklarativt definert i YAML-filen.
  1. Modul: Ny fil opax-mcp/gitea_handler.py opprettes. Dette blir en intern modul i opax-mcp-servicen, ikke en egen microservice.
  2. Logikk: opax-mcp/server.py importerer gitea_handler og delegerer alle Gitea-relaterte kall (list_repo_files, update_file, etc.) dit. CICD-kall forblir i server.py.
  3. Autentisering:
    • Ekstern (klient → OPAX-MCP): Håndteres av IAP, som i dag. Ingen endring.
    • Intern (OPAX-MCP → Gitea): gitea_handler.py bruker et dedikert API-token til å autentisere seg mot Gitea.
  4. Secrets: opax-mcp.yaml må oppdateres med GITEA_URL og en referanse til secret GITEA_API_TOKEN_SECRET.

Fase 3: Gitea-drevet CI/CD

  • Mål: Sikre at Cloud Build utelukkende trigges av git push til Gitea.
  • Filer/Tjenester: Cloud Build Triggers, Gitea webhooks, cloudbuild.yaml.
  • Verifisering: Et git push til Gitea starter en ny kjøring i Cloud Build.
  • Ferdig-kriterie: CI/CD-pipelinen er 100% Gitea-drevet.

Fase 4: Fjerne GitHub fra daglig drift

  • Mål: Fjerne alle operative bindinger til GitHub.
  • Filer/Tjenester: cloudbuild.yaml (GitHub App-kobling), diverse skript.
  • Verifisering: Ingen skript eller pipelines feiler etter at GitHub-integrasjoner er fjernet.
  • Ferdig-kriterie: GitHub er kun en passiv backup.

🎯 NESTE OPPGAVE (prioritert)

1. Installer Ollama på osvauco-dev-vm

curl -fsSL https://ollama.com/install.sh | sh
sudo systemctl enable ollama
sudo sed -i 's|ExecStart=.*|ExecStart=/usr/local/bin/ollama serve|' /etc/systemd/system/ollama.service
sudo sed -i '/ExecStart/a Environment="OLLAMA_HOST=0.0.0.0"' /etc/systemd/system/ollama.service
sudo systemctl daemon-reload && sudo systemctl restart ollama

2. Pull modeller

ollama pull gemma3:4b      # 3.3 GB — lett, rask
ollama pull qwen2.5:7b     # 4.7 GB — sterkere

3. Test Ollama

curl http://localhost:11434/api/generate -d '{"model":"gemma3:4b","prompt":"hei","stream":false}'

4. Oppdater opax-mcp/server.py (PARKERT/ERSTATTET)

  • Note: Erstattet av Fase 1: opax-mcp.yaml som autoritativ deploy-path. Kodeendringer til opax-mcp skal følge den nye, stabile deploy-prosessen.

5. Oppdater boot.sh — Ollama autostart-sjekk

  • Legg til seksjon [ OLLAMA ] i scripts/boot.sh som sjekker at Ollama kjører

6. Emma-gpu-vm — kun ved behov

  • Legg til aliaser i boot.sh:
    • emma-start — starter emma-gpu-vm
    • emma-stop — stopper emma-gpu-vm

🖥 Infrastruktur per 2026-06-29

Ressurs Spec Status Kostnad/mnd
osvauco-dev-vm e2-standard-4, 16GB RAM, 50GB SSD, us-central1-b ✅ Kjører ~NOK 550
emma-gpu-vm GPU, europe-west4-a 💤 Stoppet ~NOK 30 (kun disk)
Cloud Run opax-mcp MCP-server, us-central1 ✅ Kjører ~NOK 50
Cloud Run osvauco-agent Hovedagent, us-central1 ✅ Kjører inkl. over
Load Balancer + DNS opax.vauco.no, 34.98.77.173 ✅ Kjører ~NOK 150
TOTAL ~NOK 780/mnd

Tidligere kostnad (emma alltid på): NOK 6,000+/mnd

✅ Fullført i dag (2026-06-29)

Oppgave Status
git remote origin endret fra GitHub til Gitea på aktiv dev-VM (osvauco-gpu-vm) ✅
github-remote fjernet (duplikat) ✅
git pull origin main fungerer igjen ✅
boot.sh kjører komplett uten å henge ✅
osvauco-dev-vm oppgradert: e2-medium → e2-standard-4 (16GB RAM) ✅
Disk utvidet: 20GB → 50GB ✅
emma-gpu-vm stoppet (spare kostnad) ✅
GitHub avviklet som primær kilde, Gitea er nå master ✅

emma-gpu-vm er klargjort, men ikke tatt i bruk som primær dev-node ennå.

🔑 Credentials

  • GitHub PAT: Secret Manager → GITHUB_PAT (oppdatert 2026-06-25)
  • MCP-Secret: Secret Manager → mcp-server-key
  • Prosjekt: propane-will-491900-m5
  • IAP OAuth Client ID: 357036551735-kq8nt7ld38hfqlcfb3n52ef7tala4meo.apps.googleusercontent.com
  • VM compute SA: 357036551735-compute@developer.gserviceaccount.com
  • Ollama (når installert): http://localhost:11434
  • Emma-gpu-vm IP: 34.13.238.133 (kun når startet)

🏗 Arkitektur (nå)

Bruker
  └─► Jason (Vertex AI Agent Engine, Gemini 2.5 Pro)
        └─► osvauco-agent (Cloud Run)
              └─► opax-mcp (Cloud Run, 16 tools)
                    └─► [IAP] opax.vauco.no

osvauco-dev-vm (e2-standard-4, 16GB)
  └─► Gemini CLI / Claude CLI (opax/opax2)
  └─► Ollama (localhost:11434) ← INSTALLERES NESTE
        ├─► gemma3:4b  (lett)
        └─► qwen2.5:7b (sterk)
  └─► Emma (lokal agent)
        ├─► Morfisk minne (SQLite)
        ├─► Guardrails (5-nivå)
        └─► OPAX-klient

emma-gpu-vm (stoppet — start ved behov)
  └─► gemma3:27b (tung modell for kunder)

🔑 TILGANGSMODELL OG PROFILER

Beslutning:

  • OPAX-MCP er felles ekstern gateway over HTTPS.
  • Repo- og driftsverktøy er kun for operator-profiler.
  • Familieprofiler og senere sluttbrukerprofiler skal ikke ha generell repo-oversikt eller generiske kodeverktøy.
  • Sluttbrukere får kun oppgavebaserte capabilities med avgrenset scope.
  • Nye brukere og nye hjem/oppsett skal på sikt kunne opprettes via blueprints/profiler, ikke via full teknisk tilgang.

Operativ tolkning:

  • “Ekstern klient” betyr Perplexity, mobilflater, familieassistenter og andre agenter/VM-er som ikke skal ha direkte tilgang til intern repo/serverstruktur.
  • Disse klientene skal gå via OPAX-MCP, ikke direkte mot Gitea eller interne driftstjenester.
  • Full repo-innsikt, push/write og driftstools forblir for operatornivå.
  • Familie- og sluttbrukerflater skal eksponere trygge, oppgavebaserte funksjoner i stedet for generelle utviklerverktøy.
  • Arkitekturen skal støtte én kjerneplattform med ulike profiler: Operator, Family og senere kunde/hjem-blueprints.

PROFILMODELL – HVEM FÅR HVA VIA OPAX-MCP

Operator-profil (deg og evt. få betrodde)

  • Full tilgang til OPAX-MCP-verktøy for repo, drift og CICD.
  • Kan lese og skrive direkte mot Gitea via Gitea-capability (list_commits, get_file, push_file, issues).
  • Kan trigge og overvåke Cloud Build / Cloud Run via CICD-capability.
  • Kan endre arkitektur, secrets og konfigurasjon når det er nødvendig.
  • Krav: sterk auth (MCP_SECRET), bevisst bruk, og commit/push-praksis mot Gitea som sannhet.

Family-profil (familie og nærmeste)

  • Ingen generell repo-innsikt og ingen generiske kodeverktøy.
  • Tilgang til oppgavebaserte capabilities (f.eks. familieplan, handleliste, meldinger, status) via OPAX-MCP.
  • Kan bruke agenter og assistenter som går via OPAX-MCP, men bare innenfor trygge, avgrensede flows.
  • Repo-tilgang for family skjer indirekte, som del av oppgaveverktøy, ikke som “fri coding”.
  • Krav: enkel, mobilvennlig auth og minimal risiko for å påvirke drift eller arkitektur.

Blueprint-/kunde-/hjem-profiler (senere)

  • Malbaserte profiler som beskriver hvilket sett med capabilities og hvilke grenser en ny “hjem” eller kunde får.
  • Hver blueprint definerer:
    • Hvilke moduler som er aktive (Gitea-lesing, meldinger, økonomi, osv.).
    • Hvilke verktøy er synlige i OPAX-MCP for den profilen.
    • Hvilke ressurser (repoer, prosjekter, noder) er innenfor scope.
  • Opprettelse av nye profiler skal skje som en bevisst handling via blueprint, ikke via ad-hoc åpning av hele systemet.

Tilgangsmatrise – Gitea Capabilities (Fase 2):

  • Operator-profil:
    • Repo-lesing: Full tilgang.
    • Repo-skriving: Full tilgang.
  • Family-profil:
    • Repo-lesing: Kun tilgang til spesifikke, trygge funksjoner (f.eks. get_file_content for en handleliste). Ingen generell fil-listing.
    • Repo-skriving: Ingen tilgang.
  • Blueprint/Kunde/Hjem-profil:
    • Repo-lesing: Ingen tilgang som standard. Må aktiveres eksplisitt i blueprint.
    • Repo-skriving: Ingen tilgang som standard.

🔁 LÆRINGSSLØYFE FOR AGENTER OG LLM-DRIFT

Mål:

  • Systemet skal forbedres mens vi jobber, ikke bare etterpå.
  • Høyere kvalitet skal komme fra bedre dataflyt, bedre seleksjon og bedre feedback, ikke bare større modeller.

Prinsipper:

  • Good data beats more data: verifiserte hendelser, faktiske diff-er, reelle feil og ekte outcome-logg er mer verdifulle enn mye støy.
  • Bad data compounds: feil antakelser, uverifiserte forklaringer og gamle docs som behandles som sannhet skal ikke mates tilbake ukritisk.
  • Scaling laws i praksis: mer kontekst, flere steg og mer historikk gir bare bedre resultater hvis datakvaliteten holdes høy.
  • Moore’s law betyr at rå compute over tid blir billigere og mer tilgjengelig, men det løser ikke alene kvalitetsproblemet i agent- og LLM-drift.
  • Bedre hardware uten bedre datahygiene gir bare raskere produksjon av de samme feilene. Derfor skal systemet utnytte begge lover samtidig: Moore’s law på compute-siden, og scaling laws på modell/data-siden.
  • Arbeidslogg, handoff, learnings og verifiseringsoutput skal brukes som kuratert læringsgrunnlag for neste agent og senere trenings-/finetunegrunnlag.
  • Hver økt skal produsere små, høyverdige datapunkter: diagnose, plan, apply, verifisering, avvik, beslutning.
  • Praktisk betyr det at mer GPU, mer kontekst og større modeller først gir varig verdi når læringsgrunnlaget er kuratert, verifisert og forankret i reell drift.
  • Strategien er: bruk økende compute til å forsterke god læring, ikke til å skalere opp støy.

Operativ regel:

  • Agenter skal ikke “lære” av egne antakelser alene.
  • De skal lære av dokumentert virkelighet: rå output, godkjente diff-er, bekreftede feil, bekreftede fixes og tydelig markerte blockers.

Bruk:

  • Dette gjelder Gemini på VM, OPAX-MCP, fremtidige LLM API-agenter og senere intern eval/finetune/RAG.
  • Målet er at neste agent starter klokere enn forrige, uten å arve ukritisk støy.

🚚 Gitea-migreringsplan

Diagnose har avdekket at en aktiv Gitea-instans kjører på en midlertidig VM, og at lastbalanserer peker feil. Dette løses ved en kontrollert migrering til en ny, permanent VM, ikke ved å fikse den gamle.

  • Kilde-VM: osvauco-dev-from-snap (i us-west4-a)

  • Kilde-data: /opt/gitea/data/ (inneholder app.ini med ROOT_URL=http://34.170.51.84:3000/)

  • Mål-VM: Ny gitea-cpu-vm (i us-central1-b, som per arkitekturbeslutning)

  • Mål-data: /opt/gitea/data/

Nøkkelsteg ved migrering:

  1. Data fra kilde-VM må kopieres til mål-VM.
  2. ROOT_URL i app.ini på mål-VM må oppdateres fra http://34.170.51.84:3000/ til https://git.vauco.no/.
  3. Lastbalanserer-backend (vauco-os-backend) må pekes til den nye gitea-cpu-vm etter at migreringen er testet og verifisert.

📚 Relevante docs

Dok Innhold
docs/LEARNINGS.md Append-only lærdomslogg
docs/AGENT_RULEBOOK.md Boot-protokoll, deploy-regler
.gemini/GEMINI.md Instrukser til Gemini CLI på VM
scripts/boot.sh Session-starter, aliaser, TUI-valg
scripts/vm-teardown.sh Cron 03:00 CEST — stopper dev-vm
docs/DNS-OG-INFRASTRUKTUR.md DNS-kart, IAP-routing

HANDOFF 2026-07-07: Etablering av autoritativ deploy-pipeline

Mål: Gjøre opax-mcp.yaml til den eneste autoritative sannheten for deploy av opax-mcp-tjenesten, og fjerne den gamle, manuelle deploy-flyten.

1. Analyse og opprydding av opax-mcp.yaml

  • Analyse: En "diff" mellom live Cloud Run-tjenesten og opax-mcp.yaml avdekket avvik. Live hadde gamle GitHub-variabler, mens YAML-filen hadde mange nye (Gitea, Twilio, Gmail).
  • Beslutning: For å gjøre første autoritative deploy så trygg som mulig, ble det besluttet å midlertidig fjerne Gitea-spesifikke variabler (GITEA_URL, GITEA_TOKEN) fra opax-mcp.yaml.
  • Resultat: opax-mcp.yaml er patchet og committet. Den representerer nå en ren basis-konfigurasjon uten aktiv Gitea-runtime.

2. Opprettelse av deklarativ pipeline (cloudbuild.deploy.yaml)

  • Analyse: Den eksisterende cloudbuild.mcp.yaml brukte en imperativ gcloud run deploy-kommando som overstyrte manifest-filen.
  • Beslutning: En ny, dedikert og deklarativ pipeline-fil ble opprettet.
  • Resultat: cloudbuild.deploy.yaml er opprettet og committet. Den bygger et image med unik $BUILD_ID, rendrer en midlertidig kopi av opax-mcp.yaml med den nye image-taggen, og deployer med gcloud run services replace.

3. Rekonfigurering av Cloud Build Trigger (feilet)

  • Mål: Peker den eksisterende Gitea-webhook-triggeren (gitea-osvauco-main) fra den gamle cloudbuild.mcp.yaml til den nye cloudbuild.deploy.yaml.
  • Problem: gcloud-CLIet for å oppdatere/gjenopprette webhook-triggere viste seg å være kantete og feilet gjentatte ganger.
  • Resultat: Den gamle triggeren ble slettet i et forsøk på å gjenopprette den, men gjenopprettingen feilet. Plattformen er derfor uten en aktiv CI/CD-trigger for opax-mcp akkurat nå.

4. Strategisk avklaring og neste steg

  • Vurdering: Banen med Cloud Build webhooks er teknisk mulig, men føles som en unødvendig kompleks tilpasning. En egen, OPAX-styrt deploy-bro (Modell B) er et bedre langsiktig mål.
  • Beslutning: Vi fullfører den enkle webhook-flyten (Modell A) nå for å få en automatisert pipeline raskt, men planlegger for Modell B senere.

Status og neste konkrete handling

Artefakt Status
opax-mcp.yaml ✅ Klar for autoritativ deploy (midlertidig uten Gitea-vars)
cloudbuild.deploy.yaml ✅ Klar og committet
Cloud Build Trigger 🔴 MANGLER. Må gjenopprettes manuelt.

Neste handling: Gjenopprett gitea-osvauco-main manuelt i Cloud Console med den nye cloudbuild.deploy.yaml som byggefil for å re-aktivere CI/CD-pipelinen.