Status: Proposed Datum: 2026-05-07 Oblast: Plugin systém / Stopa B

Context

Stopa B — cloud deploy user-generated apps

Stopa B přidává do platformy schopnost buildit a deployit user-generated apps do K8s. Po deployi je app dostupná na URL <slug>.talkide.app (PROD) nebo <uuid>.talkide.app (DEV preview).

Součástí Stopy B je otázka: kdo a kdy iniciuje DEV preview deploy po dokončení Mařina tasku?

URL konvence (Stopa B.5)

Alternativy

Varianta A — Mara přímo iniciuje deploy Mara po každém taskCompletion zavolá deploy endpoint. Porušuje single-responsibility: Mara je PM a orchestrátor, ne ops agent. Navíc Mara nemá tools pro sledování build statusu.

Varianta B — BE auto-trigger watcher Backend sleduje aktivitu projektu a po každém tasku automaticky spustí build. Žádné smart decision rules — deploy by se spustil i po Q&A only konverzaci nebo při pouhém čtení kódu. Předražené (Kaniko build na každou konverzaci) a bez možnosti debounce na úrovni agenta.

Varianta C — druhý dedikovaný LLM Kai agent jako orchestrátor Real LLM agent zodpovědný výhradně za cloud ops. Extra LLM cost, extra složitost — nový agent bez jednoznačného domainového obsahu, protože jeho veškerá logika by byly jen decision rules.

Varianta D (zvolená) — rozšíření existujícího Kai / talkide-devops persona Kai (= talkide-devops.md) je environment-aware: v local módu dělá to co dnes (start/stop, build), v cloud módu zavolá HTTP endpoint TalkIDE platformy a sleduje SSE build status. Decision rules pro deploy žijí přímo v Kaiově system promptu — jsou rozšiřitelné a testovatelné v izolaci.

Decision

Kai je environment-aware agent

talkide-devops.md (= Kai persona) se rozšiřuje o Cloud Mode sekci.

Detekce prostředí

Kai pozná cloud z env vars injektovaných do Mařina conversation contextu (přidáváme do .talkide/project.yml a šíříme přes project.yml → spawn Claude CLI → env):

TALKIDE_ENVIRONMENT=cloud       # absent nebo "local" = lokál mód
TALKIDE_PROJECT_ID=42
TALKIDE_DEPLOY_ENDPOINT=http://localhost:8080/api/internal/build-and-deploy

Kai čte tyto hodnoty jednoduše z env a nepotřebuje parsovat YAML sám. TALKIDE_DEPLOY_ENDPOINT míří na localhost:8080 — Kai sidecar volá BE přes sdílený network namespace K8s podu.

Dva módy, jeden Kai

Decision rules pro cloud deploy

Kai sám rozhoduje, zda deploy spustit. Pravidla v system promptu:

HARD RULE — PROD je vždy manuální

PROD “Publish” deploy je VŽDY user manual click v TalkIDE UI. Kai nemá tool ani script pro PROD deploy. Žádný AI-iniciovaný deploy do produkce. Toto pravidlo je absolutní a nemá výjimky.

Synchronous UX v cloudu

User → Mara: "Přidej endpoint pro seznam produktů"
Mara → Theo + Eli: implementace (parallel)
Theo/Eli → Mara: hotovo
Mara → Kai: "Předávám pro cloud deploy"
Kai: zavolá deploy-preview.sh → sleduje SSE stream ("Building... 1m 23s")
Kai → Mara: "Deploy hotov, DEV URL: https://<uuid>.talkide.app"
Mara → User: "Endpoint je live, vidíš v náhledu."

Frontend BE SSE stream zobrazí “Building 1m 23s…” během čekání — uživatel vidí živý progress místo spinning loaderů bez kontextu.

Implementation Plan

Detailní specs jdou do GitLab issues. Tento plán je high-level záchytný bod.

1. Update talkide-be/plugin/agents/talkide-devops.md

• Přidat sekci Cloud Mode s decision rules (tabulky výše)
• Přidat environment detection logic (čtení TALKIDE_ENVIRONMENT, TALKIDE_PROJECT_ID, TALKIDE_DEPLOY_ENDPOINT)
• Přidat reference na nový script deploy-preview.sh
• Zachovat veškerou existující Local Mode logiku beze změny

2. Nový plugin script talkide-be/plugin/scripts/deploy-preview.sh

• Bash wrapper kolem curl -N POST $TALKIDE_DEPLOY_ENDPOINT (SSE streaming)
• Auth: žádný token — endpoint je IP-locked na 127.0.0.1 / ::1; Kai volá BE přes localhost
• Body: {"tenantId": ..., "slug": ..., "env": "dev", "projectUuid": ...} — hodnoty načteny z env nebo fallback yq .cloud... .talkide/project.yml
• Streamuje SSE response na stdout, parsuje event: phase / event: error:

  event: phase    data: {`{`}"phase":"BUILDING","buildId":"..."{`}`}
  event: phase    data: {`{`}"phase":"BUILT","buildId":"...","imageTag":"..."{`}`}
  event: phase    data: {`{`}"phase":"DEPLOYING"{`}`}
  event: phase    data: {`{`}"phase":"LIVE","previewUrl":"https://<uuid>.talkide.app"{`}`}
  event: error    data: {`{`}"code":"BUILD_FAILED|TIMEOUT|K8S_DEPLOY_ERROR","message":"..."{`}`}
  

• Exit 0 na phase=LIVE, exit 1 na event: error nebo timeout (>10 min)

3. BE endpoint — Stopa B.4 (BE#62)

POST /api/internal/build-and-deploy

• Auth: IP-locked na 127.0.0.1 / ::1 (InternalEndpointSecurityConfig) — žádný token
• Spustí Kaniko build → K8s deploy pipeline
• Vrátí SSE stream s event: phase / event: error (kontrakt viz sekce 2 výše)
• Idempotent: pokud build již běží, vrátí existující SSE stream (debounce na BE straně)
• Úplná specifikace endpointu: BE#62

4. .talkide/project.yml — schema extension

cloud:
  uuid: "a1b2c3d4-..."          # persistentní UUID, generuje BE při prvním deploy
  project_id: 42
  tenant_id: 7                  # vyžaduje BE#62 v request body

urls:
  # existující:
  backend: "http://localhost:8097"
  frontend: "http://localhost:5207"
  # nové:
  dev_cloud: "https://a1b2c3d4.talkide.app"   # po prvním cloud deployi
  prod_cloud: "https://moje-app.talkide.app"  # po user Publish

5. Migration path (Stopa D nebo E)

Tato architektura je záměrně přechodná. Kai jako rozšířená persona je easy migration path: až bude dávat smysl real Kai LLM orchestrátor (vlastní conversation loop, složitější CD pipeline, multi-env orchestrace), přesuneme decision rules z talkide-devops.md do nového agenta — bez změny BE endpointů nebo project.yml schématu.

Consequences

Pozitiva

• Konzistence local + cloud mental model — Kai dělá deploy v obou módech, uživatel nevidí žádný rozdíl v tom, kdo “spouští věci”.
• Žádný extra LLM cost — Kai již existuje, pouze se rozšiřuje system prompt.
• Smart decision rules na úrovni Kai promptu — lze snadno iterovat (přidat rule, změnit debounce) bez BE změn.
• Easy migration path do real Kai LLM orchestrátoru v budoucnu.
• Testovatelné v izolaci — deploy-preview.sh lze zavolat ručně pro debugging.

Rizika a omezení

• UX blocking — Kaiova conversation v cloudu trvá ~3–5 min (Kaniko build). Uživatel musí čekat. Mitigace: SSE progress stream v UI.
• Plugin update nutný — talkide-devops.md a nový deploy-preview.sh musí být nasazeny synchronně. Lazy rsync guard (ADR-011) zaručuje propagaci do per-project kopií při dalším spawn.
• Kai sidecar musí běžet ve stejném K8s podu jako TalkIDE BE — sdílený network namespace je předpokladem pro IP-localhost auth check. Pokud by Mara/Kai běžel mimo BE pod (např. budoucí škálování nebo multi-tenant separace), musí se auth model rozšířit (API key, mTLS, nebo interní service mesh policy). Tato závislost je záměrně zjednodušená pro MVP.
• Varianta B zůstává jako fallback — pokud by se decision rules v Kaiově promptu ukázaly jako nedostatečné, BE watcher lze přidat jako opt-in (flag v project.yml). Není součástí tohoto ADR.