till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-20 00:01:24 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

feat(mana-ai): v0.7 — cross-tick Deep Research Max pre-planning

Browse source 
Opt-in path for missions that want Gemini Deep Research Max (up to 60 min
per task) instead of the shallow RSS pre-research. Because Max runs well
past a single 60-second tick, the state is carried across ticks:

  tick N:   submit → INSERT mission_research_jobs row → skip planner
  tick N+k: poll → still running → skip planner (metric pending_skips)
  tick N+m: poll → completed → inject as ResolvedInput, DELETE row, plan

- ManaResearchClient talks to mana-research's new internal
  /v1/internal/research/async endpoints with X-Service-Key +
  X-User-Id. Graceful-null on transport errors so a flaky
  mana-research never crashes the tick loop.
- New table mana_ai.mission_research_jobs with PK (user_id, mission_id)
  — presence is the "pending" flag; delete-on-terminal keeps queries
  trivial.
- handleDeepResearch() encapsulates the state machine; planOneMission
  now returns a discriminated union (planned | skipped | failed) so
  "research pending" isn't miscounted as a parse failure.
- Opt-in at TWO gates to keep cost in check ($3–7/task, 1500 credits
  per run):
    1. MANA_AI_DEEP_RESEARCH_ENABLED=true server-side (default off)
    2. DEEP_RESEARCH_TRIGGER regex matches the mission objective
       (strict: "deep research", "tiefe recherche", "umfassende
       recherche", "hintergrundrecherche", "deep dive")
  Falls back to shallow RSS when either gate fails or the submit
  errors upstream.
- Prom metrics: mana_ai_research_jobs_{submitted,completed,failed}_total
  labelled by provider, plus _pending_skips_total.
- docker-compose wires MANA_RESEARCH_URL + the opt-in flag and adds
  mana-research to depends_on.
- Full write-up with real API response shape (outputs plural, not
  OpenAI-style), step-3 MCP-server plan (security-gated, not built),
  ops + kill-switch: docs/reports/gemini-deep-research.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Till JS 2026-04-22 17:56:06 +02:00
parent f10a95e842
commit 2a18cb5ee4
12 changed files with 947 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

431
docs/reports/gemini-deep-research.md Normal file
View file

@ -0,0 +1,431 @@
# Gemini 3.1 Pro Deep Research & Deep Research Max
**Datum:** 2026-04-22
**Anlass:** Googles Launch am 2026-04-21 — zwei autonome Research-Agenten auf Basis von Gemini 3.1 Pro, verfügbar als Public Preview über die Gemini API.
**Status:** Schritt 1 + 2 geliefert. Schritt 3 (MCP-Server) geplant, nicht implementiert.
## TL;DR
Google hat zwei neue Research-Agenten veröffentlicht, die bei uns direkt in die Provider-Landschaft von `mana-research` passen und die Phase-3b-Lücke (`openai-deep-research` als einziger async Agent) auf natürliche Weise ergänzen. Besonderheit: **beide Agenten sprechen Model Context Protocol (MCP)**, wodurch sie potenziell an *unsere* Daten andocken könnten — was in Kombination mit dem existierenden AI-Mission-Key-Grant-System (RSA-wrapped MDK, audit-logged) ein strategisch interessanter Vektor ist.
Schritt 1 (async Provider) und Schritt 2 (`mana-ai` Cross-Tick-Pre-Research) sind geliefert und hinter einem Opt-in-Flag (`MANA_AI_DEEP_RESEARCH_ENABLED=true`) aktivierbar. Schritt 3 (MCP-Server für unsere verschlüsselten Kontextdaten) ist spezifiziert, aber Security-Review erforderlich vor Rollout.
## 1. Die Modelle im Detail
### 1.1 Varianten und Positionierung
| | **Deep Research** | **Deep Research Max** |
|---|---|---|
| **Model-ID** | `deep-research-preview-04-2026` | `deep-research-max-preview-04-2026` |
| **Zielbild** | Interaktiv, niedrige Latenz, eingebettet in User-Surfaces | Asynchron, nächtliche Cron-Jobs, maximale Tiefe |
| **Typ. Laufzeit** | Minutenbereich (eingebaut in Chat-UIs) | Bis zu 60 min (typ. ~20 min) |
| **Typ. Volumen** | ~80 Suchen, ~250k Input-Tokens, ~60k Output | ~160 Suchen, ~900k Input-Tokens, ~80k Output |
| **Preis (geschätzt)** | $1.00–3.00 pro Task | $3.00–7.00 pro Task |
| **DeepSearchQA** | — | 93.3 % (von 66.1 % im Dez 2025) |
| **Humanity's Last Exam** | — | 54.6 % (von 46.4 %) |
Beide laufen ausschließlich **async** (`background=true` ist Pflicht, `store=true` erforderlich). Es gibt keinen synchronen Request-Response-Modus wie bei `gemini-grounding`.
### 1.2 API-Shape — submit
```
POST https://generativelanguage.googleapis.com/v1beta/interactions
x-goog-api-key: <GOOGLE_GENAI_API_KEY>
Content-Type: application/json
{
"agent": "deep-research-preview-04-2026",
"input": "query",
"background": true,
"store": true,
"agent_config": {
"type": "deep-research",
"thinking_summaries": "auto", // Live-Gedanken streamen
"visualization": "auto", // Charts/Infographics inline
"collaborative_planning": false
},
"tools": [
{ "type": "google_search" },
{ "type": "url_context" },
{ "type": "code_execution" },
{ "type": "file_search" },
{
"type": "mcp_server",
"name": "mana-kontext",
"url": "https://mcp.mana.how/...",
"headers": { "Authorization": "Bearer …" },
"allowed_tools": ["search_notes", "search_journal"]
}
]
}
→ 200
{
"id": "v1_Chd...",
"status": "in_progress",
"role": "agent",
"created": "...",
"agent": "deep-research-preview-04-2026"
}
```
### 1.3 API-Shape — poll (completed)
Die tatsächlich beobachtete Response-Shape (Smoke-Test am 2026-04-22) weicht von der OpenAI-Responses-API deutlich ab. Wir hatten initial OpenAI-Style (`output: [{type:'message', content:[...]}]`) erwartet — die echte Shape sieht so aus:
```
GET https://generativelanguage.googleapis.com/v1beta/interactions/{id}
→ 200
{
"id": "v1_Chd...",
"status": "completed",
"outputs": [ // Plural! Flaches Array.
{ "type": "thought",
"signature": "...",
"summary": [ // Thought-Summaries als Liste
{ "type": "text", "text": "..." }
]
},
{}, // Gelegentlich leer → ignorieren
{ "type": "text",
"text": "# Hono and Bun...",
"annotations": [
{ "type": "url_citation",
"url": "https://...",
"start_index": 268,
"end_index": 283
}
]
},
{ "type": "image",
"mime_type": "image/png",
"data": "<base64>" // Charts/Infographics
},
{ "type": "text", "text": "**Sources:** ..." }
],
"usage": {
"total_tokens": 145268,
"total_input_tokens": 93025,
"total_output_tokens": 7770,
"total_cached_tokens": 16384, // Prompt-Cache
"total_tool_use_tokens": 28371,
"total_thought_tokens": 16102,
"input_tokens_by_modality": [...],
"output_tokens_by_modality": [...]
},
"role": "agent",
"object": "interaction",
"agent": "deep-research-preview-04-2026"
}
```
Wichtig für den Parser:
- **`outputs` (nicht `output`)** ist ein flaches Array mit `type: 'thought' | 'text' | 'image' | null`
- `text` items haben `annotations[]` mit `type: 'url_citation'`, `url`, `start_index`/`end_index` — **kein `title`-Feld**, wir ziehen den Hostname aus der URL
- `image` items tragen base64-codierte Bilder (PNG) als `data` mit `mime_type`
- `thought` items sind die live-gestreamten Reasoning-Summaries — wenn wir nur den finalen Report brauchen, skip
- `usage` nutzt `total_input_tokens` / `total_output_tokens` (nicht `input_tokens` / `output_tokens`)
### 1.4 Was die Agenten können
- **Autonom planen** und iterativ nachsuchen, bis sie eine Antwort haben
- **Google Search + URL Context + Code Execution + File Search** parallel oder einzeln; Web-Zugriff lässt sich auch komplett deaktivieren (Pure-MCP-Mode)
- **MCP-Server** als Brücke zu proprietären Datenquellen — Enterprise-Partner sind FactSet, S&P Global, PitchBook
- **Native Visualisierung**: Charts und Infographics inline als HTML oder Nano-Banana
- **Thought-Summaries** als Live-Stream — brauchbar für "Agent denkt gerade…"-UIs
- **Keine** Structured Outputs, **keine** custom Function-Calls (dafür gibt es MCP)
## 2. Einordnung in unsere Landschaft
### 2.1 `mana-research` (port 3068)
Phase 3a liefert vier **synchrone** Agents (`perplexity-sonar`, `gemini-grounding`, `openai-responses`, `claude-web-search`). Phase 3b war ursprünglich nur für `openai-deep-research` (1000 credits) vorgesehen; mit Schritt 1 kommen die beiden Gemini-Async-Provider dazu und verdoppeln die Abdeckung des Max-Tiers.
### 2.2 `mana-ai` (port 3067)
v0.6 hatte den RSS-basierten `NewsResearchClient` und den **Pre-Planning-Research-Step** geshipped. Mit Schritt 2 (v0.7) kommt daneben ein zweiter Pfad: wenn eine Mission explizit nach deep research fragt und der Service die entsprechende ENV-Flag gesetzt hat, wird statt RSS eine async Gemini Deep Research Max Task submittet und über Ticks hinweg gepollt.
## 3. Integrationsplan — Status
| Schritt | Status | Datum | Details |
|---|---|---|---|
| 1 — Gemini als async Provider in mana-research | ✅ Geliefert | 2026-04-22 | §3.1 |
| 2 — Cross-Tick Deep-Research in mana-ai | ✅ Geliefert | 2026-04-22 | §3.2 |
| 3 — MCP-Server für unsere Daten | ⏳ Spezifiziert | — | §3.3 |
### 3.1 Schritt 1 — `gemini-deep-research[-max]` als async Provider — ✅ GELIEFERT
Zwei neue Provider-IDs neben `openai-deep-research` in `mana-research`:
**Geänderte/neue Dateien:**
- `packages/shared-research/src/ids.ts` — `AGENT_PROVIDER_IDS` erweitert um `gemini-deep-research` + `gemini-deep-research-max`
- `services/mana-research/src/providers/agent/gemini-deep-research.ts` — neuer Provider, submit/poll-Split tier-parametrisiert (`standard`/`max`). Parser nutzt die echte Response-Shape aus §1.3.
- `services/mana-research/src/routes/research.ts` — `/async` POST + `/async/:id` GET dispatchen via `dispatchAsync(providerId, config)`. Default: `openai-deep-research` (backward compatible).
- `services/mana-research/src/routes/internal-research.ts` — **neu** — service-to-service Pendant unter `/api/v1/internal/research/async`, gated durch `X-Service-Key` + `X-User-Id` Header für Credit-Accounting.
- `src/lib/pricing.ts` — 300 / 1500 credits (Standard / Max)
- `src/executor/env-map.ts` + `src/router/auto-route.ts` — beide neue IDs auf `googleGenai`, explizit **nicht** in `AGENT_DEFAULT_ORDER` (sync-Auto-Route überspringt sie; nur `/async` erreichbar)
- `src/routes/providers.ts` — Health-keyMap ergänzt
- `src/index.ts` — internal route gemountet unter `/api/v1/internal/research/*`
- `services/mana-research/API_KEYS.md` + `CLAUDE.md` — dokumentiert
**Use (user-facing):**
```
POST /api/v1/research/async
{ "query": "…", "provider": "gemini-deep-research-max" }
→ { taskId, status: "queued", providerId, costCredits: 1500 }
GET /api/v1/research/async/:taskId
```
**Use (service-to-service):**
```
POST /api/v1/internal/research/async
X-Service-Key: <MANA_SERVICE_KEY>
X-User-Id: <userId>
{ "query": "…", "provider": "gemini-deep-research-max" }
```
**Verifiziert** mit echtem `GOOGLE_GENAI_API_KEY` am 2026-04-22: submit + poll über Googles Preview-API → HTTP 200 in beiden Richtungen, completed Response korrekt geparst.
### 3.2 Schritt 2 — `mana-ai` v0.7 Cross-Tick Deep Research — ✅ GELIEFERT
**Problem:** Max-Tasks laufen bis 60 min. Der mana-ai Tick-Loop läuft alle 60 s. Wir brauchen Cross-Tick-State, um genau einen pending Research-Job pro Mission zu tracken und über mehrere Ticks zu pollen, ohne neu zu submitten.
**Geänderte/neue Dateien:**
- `services/mana-ai/src/clients/mana-research.ts` — **neu** — HTTP-Client für die internen Async-Endpoints. Graceful-null bei Fehler, damit eine kaputte mana-research den Tick nicht crasht.
- `services/mana-ai/src/db/migrate.ts` — neue Tabelle `mana_ai.mission_research_jobs (user_id, mission_id, task_id, provider_id, submitted_at, last_polled_at)` mit PK `(user_id, mission_id)`. Ein Row = es läuft ein Job.
- `services/mana-ai/src/db/research-jobs.ts` — **neu** — `get/insert/touch/delete`. Nach `completed`/`failed`: DELETE.
- `services/mana-ai/src/cron/tick.ts`:
- neuer `handleDeepResearch(m, sql, config)` mit State-Machine:
- Wenn pending Job existiert → poll
- `queued`/`running` → `'pending'` (skip tick)
- `failed`/`cancelled` → delete, fall through zu shallow
- `completed` → delete + return ResolvedInput
- Kein Job aber `DEEP_RESEARCH_TRIGGER` + `config.deepResearchEnabled` → submit + insert → `'pending'`
- `planOneMission` Rückgabetyp auf Discriminated Union erweitert: `{outcome:'planned'|'skipped'|'failed'}` statt `T | null`, damit skipped-wegen-pending-research nicht als parse-failure gezählt wird
- Shallow RSS-Pfad läuft nur noch, wenn deep weder ein Ergebnis geliefert hat, noch pending ist
- `services/mana-ai/src/config.ts` — `manaResearchUrl` + `deepResearchEnabled` (`MANA_AI_DEEP_RESEARCH_ENABLED`)
- `services/mana-ai/src/metrics.ts` — vier neue Counter: `mana_ai_research_jobs_submitted_total{provider}`, `_completed_total{provider}`, `_failed_total{provider}`, `_pending_skips_total`
- `services/mana-ai/package.json` — `@mana/shared-research` als workspace-dep + `type-check` script
- `docker-compose.macmini.yml` — mana-ai bekommt `MANA_RESEARCH_URL`, `MANA_AI_DEEP_RESEARCH_ENABLED` (default `false`), `depends_on: mana-research`
**Opt-in-Trigger (streng enger als shallow):**
```
DEEP_RESEARCH_TRIGGER = /\b(deep research|tiefe recherche|umfassende recherche|hintergrundrecherche|deep dive)\b/i
```
Zusätzlich per ENV gegated. In Prod default off; ein expliziter Flip erlaubt Rollout nur an uns selbst / Founder-Tier zuerst.
**Flow:**
```
tick N-1: Mission X, objective: "deep research zu Thema Y"
├ RESEARCH_TRIGGER matched UND DEEP_RESEARCH_TRIGGER matched
├ config.deepResearchEnabled = true
├ client.submit(userId, "deep research zu…", "gemini-deep-research-max")
│ → { taskId, status: "queued", costCredits: 1500 }
├ INSERT INTO mana_ai.mission_research_jobs (task_id, …)
└ skip planner this tick
tick N, N+1, … während Google den Task ausarbeitet (~20 min):
├ SELECT * FROM mana_ai.mission_research_jobs WHERE (user_id, mission_id) = …
├ client.poll(userId, taskId) → { status: "running" }
├ touchPendingResearchJob() bumpt last_polled_at
└ skip planner this tick
tick N+k: Max ist fertig
├ client.poll(userId, taskId) → { status: "completed", result: { answer: {...} } }
├ DELETE FROM mana_ai.mission_research_jobs WHERE …
├ resolvedInputs.push({id:"__web-research__", content: formatDeepResearchContext(...)})
└ Planner läuft mit Deep-Research-Kontext als Input
```
**Graceful Degradation:** Wenn `mana-research` down oder der Gemini-Submit 500t, fällt die Mission auf den Shallow-RSS-Pfad zurück. Wenn ein bereits submittierter Job nicht mehr gepollt werden kann, rotiert der Row ab über `touchPendingResearchJob`, bis manuelle Intervention oder ein späterer poll Erfolg hat.
### 3.3 Schritt 3 — MCP-Server für verschlüsselte Kontextdaten — ⏳ SPEZIFIZIERT
**Warum der Aufwand:** Der Grund, warum dieses Feature gerade *für uns* strategisch ist: wir haben ein Zero-Knowledge-Crypto-Setup mit per-mission Key-Grants (RSA-OAEP-2048 wrapped MDK, HKDF-Scope-Binding, audit-logged). Das MCP-Pattern kreuzt exakt unsere Stärke (lokale, verschlüsselte Daten) mit Googles Stärke (Deep-Research-Synthese). Positioning: **"Deep Research, das deine Kontextdaten kennt — ohne sie in Google's Trainings-Pipeline zu schicken"**.
#### 3.3.1 Architektur
```
┌──────────────────┐ ┌──────────────────┐
│ Gemini DR Max │◀──────│ mana-mcp-server │ (Cloudflare-tunneled,
│ (bei Google) │ MCP │ (neu, port 3069)│ öffentlich erreichbar)
└──────────────────┘ └──────┬───────────┘
│ Bearer <mcp-token>
│ (Mission-ID, TTL-clamped)
▼
┌──────────────────┐
│ mana-auth │ verifiziert token,
│ │ lädt Mission-Grant,
│ /api/v1/mcp- │ unwrappt MDK
│ token/verify │
└──────┬───────────┘
│
▼
┌──────────────────┐ ┌─────────────────┐
│ Encrypted-Data │──────▶│ mana_sync DB │
│ Resolver │ │ (+ RLS) │
│ (re-use of │ └─────────────────┘
│ mana-ai's │
│ encrypted.ts) │
└──────────────────┘
```
Der neue Service `mana-mcp` übernimmt die Rolle des MCP-Servers für Gemini. Er:
1. **hört auf eingehende MCP-Requests** von Google (z. B. `tools/call` mit `search_notes`), authentifiziert per **Bearer-Token pro Mission**. Der Token ist kein JWT, sondern eine opaque ID, die in mana-auth auf `{missionId, userId, allowedTools, expiresAt}` aufgelöst wird — analog zum existierenden Mission-Key-Grant.
2. **verifiziert das Token** gegen mana-auth's neue `/api/v1/mcp-token/verify` Route (returned `{userId, missionId, mdk-wrapped, allowedTools}` oder 401).
3. **unwrappt den Mission-Grant** (MDK) via den existierenden `crypto/unwrap-grant.ts`-Code aus mana-ai — wird in ein geteiltes Paket `@mana/mission-grant` gehoben.
4. **liest und entschlüsselt** die relevanten Records aus `mana_sync` via den existierenden `encrypted.ts` Resolver-Pattern (ebenfalls ins gleiche Paket heben).
5. **antwortet in MCP-Shape** mit Titel + Body + URL pro gefundenem Record.
#### 3.3.2 Tool-Set (Minimal)
Start mit drei readonly Tools, alle audit-logged nach `mana_ai.decrypt_audit`:
| Tool | Signatur | Was es macht |
|---|---|---|
| `search_notes` | `(query: string, limit?: number)` | Volltext über entschlüsselte Notizen |
| `search_journal` | `(date_range?: {from,to}, query?: string, limit?: number)` | Journal-Einträge nach Datum + Query |
| `search_kontext` | `(scope: string)` | Kontext-Felder aus dem Interview (bereits strukturiert) |
Alle drei sind scoped auf die Mission — sie sehen nur Records, die der Mission-Grant in der Allowlist hat. Schreibende Tools bewusst nicht.
#### 3.3.3 Token-Lifecycle
1. **Mission-Erstellung (Webapp):** Wenn eine Mission für Deep-Research-Max konfiguriert wird, erzeugt die Webapp zusätzlich zum existierenden Key-Grant einen **MCP-Token** via `POST /api/v1/me/ai-mission-mcp-token` auf mana-auth. Der Endpoint:
- erzeugt eine opaque Bearer-ID (crypto random, 32 bytes)
- speichert sie in `mana_auth.mcp_tokens` mit `{tokenHash, userId, missionId, allowedTools, expiresAt}`
- TTL-clamped [1h, 7d] — kürzer als Key-Grants, weil das Token exakt einen Research-Run abdeckt
2. **Submit (mana-ai):** Beim Submit der Max-Task wird der MCP-Token als `headers.Authorization` in den `tools.mcp_server`-Block eingebaut, passend zum Request-Shape aus §1.2.
3. **MCP-Call (mana-mcp):** Jeder eingehende Request wird via mana-auth verifiziert. Bei `expires`/unbekanntem Token → 401. Bei OK → Resolver-Aufruf + audit-row.
4. **Teardown:** Nach Poll-Result `completed`/`failed` markiert mana-ai den Token als verbraucht (mana-auth DELETE). Auch expirte Tokens werden über einen Cron entfernt.
#### 3.3.4 Was wir neu bauen müssen
| Komponente | Umfang |
|---|---|
| `services/mana-mcp/` | Neuer Bun/Hono-Service, ~500 LOC. MCP-Protokoll (JSON-RPC über HTTP), 3 Tool-Handler, Bearer-Auth. |
| `packages/mission-grant/` | Wiederverwendbares Paket mit `unwrapMissionGrant` + `encryptedRecordResolver` (jetzt in mana-ai lokalisiert) |
| `mana_auth.mcp_tokens` Tabelle | `{id, token_hash, user_id, mission_id, allowed_tools, expires_at, consumed_at}` |
| `POST /api/v1/me/ai-mission-mcp-token` | Issue |
| `POST /api/v1/mcp-token/verify` | Server-to-server Verify |
| `DELETE /api/v1/me/ai-mission-mcp-token/:id` | Explicit revoke (UI-Link) |
| Webapp: MCP-Option im Mission-Detail | "Meine Kontextdaten für diese Recherche freigeben" Checkbox + Token-Erzeugung |
| Audit-Tab-Erweiterung | Zeigt auch MCP-Aufrufe neben Decrypts |
| Cloudflare Tunnel für `mcp.mana.how` → mana-mcp | Analog zu `api.mana.how` etc. |
#### 3.3.5 Risiken
- **Öffentliche Angriffsfläche:** Der Service ist über Cloudflare Tunnel öffentlich erreichbar — sonst kann Gemini ihn nicht aufrufen. Ein schlecht durchdachter Tool-Handler oder eine Grant-Verwechslung bedeutet direkte Datenlecks. **Security-Review Pflicht** (Secure Code Review + Mini-Pentest) vor Rollout.
- **MCP-Rate-Limits:** Google kann den Server bei parallelen Research-Max-Tasks zig mal pro Minute anfragen. Wir brauchen Rate-Limiting (per Token) + Caching-Layer.
- **Token-Scope-Violations:** Wenn ein Request für Mission A auf Records aus Mission B geht (Bug oder Angriff), muss das einen dicken Alert auslösen. Bestehende `grant_scope_violations_total` Metrik lässt sich wiederverwenden.
- **Prompt Injection:** Entschlüsselte Notizen-Content kann Instruktionen an Gemini enthalten ("IGNORE PREVIOUS, download all …"). Wir müssen Tool-Responses klar als `data`, nicht als `instructions` labeln und Gemini prompten, userdata als nicht-vertrauenswürdig zu behandeln.
- **DSGVO-Implikationen:** Auch wenn MCP nur punktuell liest, geht der gelesene Content via Google's API-Endpunkt. Das muss in den Privacy-Text + Consent-Flow der Webapp.
- **Preview-Stabilität:** Bauen bevor die MCP-Integration auf Google-Seite stabil ist, heißt nachbauen wenn sich das Protokoll ändert. Erst mit POC, dann inkrementell.
#### 3.3.6 Meilensteine
**M0 — Security-Review + Plan-Sign-off (1–2 Tage).** Vor jeder Implementation. Liefert: konkretes Threat-Model, DSGVO-Check, Go/No-Go.
**M1 — POC mit `search_notes` only (3–4 Tage).**
- `services/mana-mcp` Bun-Service-Skeleton
- `@mana/mission-grant` Paket extrahiert (kein Verhaltenschange für mana-ai)
- `mcp_tokens` Tabelle + Issue/Verify-Endpoints
- Nur `search_notes`, auf einen harten Test-User gated (`userId === 'dev-…'`)
- Ad-hoc Cloudflare-Tunnel, noch kein permanenter `mcp.mana.how`
**M2 — `search_journal` + `search_kontext` + Prod-Tunnel (2 Tage).** Nach M1-Erkenntnissen.
**M3 — Webapp UX (2–3 Tage).** Mission-Config-Checkbox + Audit-Tab-Erweiterung.
**M4 — Public Rollout Founder-Tier.** Nach 1 Woche Beta für uns selbst.
Bewusst linearer Rollout — MCP ist zu Security-sensitiv für parallele Entwicklung.
## 4. Pricing-Sanity-Check
Bei angenommenen $3–7 pro Max-Task: eine nächtliche Max-Mission pro aktivem Nutzer entspricht **$90–210/Monat pro Nutzer**. Das sitzt jetzt hinter zwei Gates:
1. `MANA_AI_DEEP_RESEARCH_ENABLED=true` auf dem Server (default off)
2. `DEEP_RESEARCH_TRIGGER` Regex im Mission-Text (explizite User-Wording)
Das `mana-credits` 2-Phase-Debit-Modell fängt Per-User-Limits ab, aber wir haben konservativ mit 1500 credits (≈ $15) für Max gepreist statt 700 (≈ $7) — als Puffer. Nach ersten echten Runs nachjustieren in `services/mana-research/src/lib/pricing.ts`.
## 5. Risiken & offene Fragen (Stand nach Schritt 1+2)
- **Preview-Status:** Model-IDs enden auf `-preview-04-2026`. Google deprecated solche Varianten typischerweise innerhalb von 6–12 Monaten. Aktuelle Strategie: `modelVersion` liegt als Konstante in `gemini-deep-research.ts` — Upgrade auf GA ist ein 1-Zeilen-Change, kein Refactor.
- **Charts/Infographics (`image`-Items):** Wir parsen sie derzeit nur in `providerRaw` — nicht im `AgentAnswer.answer` String. Follow-up: neues optionales Feld `AgentAnswer.visualizations: Array<{mime, data}>` plus MinIO-Upload für große Bilder.
- **Thought-Summaries:** Gehen heute verloren. Für eine zukünftige Research-Lab-UI wäre Streaming (`stream=true`) + Live-Anzeige der Gedanken ein differenzierendes Feature.
- **Quota:** Public Preview heißt niedrige Rate-Limits. Ersten 2 Wochen nur Founder-Tier. Monitoring via `mana_ai_research_jobs_failed_total{provider}` — sobald Spikes, Rate-Limit-Retry-Logic nachziehen.
- **`collaborative_planning: true`**: Ignoriert. Wäre ein interessanter UX-Modus für eine zukünftige **Webapp**-Research-Lab-UI (Agent fragt vor Start zurück, ob der Plan passt). Irrelevant für den Background-Runner.
- **MCP-Seite (Schritt 3):** siehe §3.3.5 — eigener Risk-Catalog.
## 6. Betrieb
### 6.1 Metriken
```
# mana-research
research.async_jobs — Tabelle, ein Row pro submit (inkl. finalem result)
# mana-ai
mana_ai_research_jobs_submitted_total{provider} — Pro Tick submittet
mana_ai_research_jobs_completed_total{provider} — Pro Tick Ergebnisse verfuettert
mana_ai_research_jobs_failed_total{provider} — Pro Tick failed/cancelled
mana_ai_research_jobs_pending_skips_total — Pro Tick skipped (Job läuft noch)
mana_ai_mission_research_jobs — Tabelle, ein Row pro pending Job pro Mission
```
### 6.2 Debug-Workflow
```bash
# Welche Missions haben aktuell einen pending Deep-Research-Job?
docker exec mana-postgres psql -U mana -d mana_sync -c "
SELECT user_id, mission_id, provider_id,
age(now(), submitted_at) AS running_for,
last_polled_at
FROM mana_ai.mission_research_jobs
ORDER BY submitted_at DESC;"
# Was ist der aktuelle Status upstream?
docker exec mana-postgres psql -U mana -d mana_platform -c "
SELECT id, user_id, provider_id, status, cost_credits, age(now(), created_at) AS age
FROM research.async_jobs
ORDER BY created_at DESC LIMIT 20;"
```
### 6.3 Notfall-Kill-Switch
`MANA_AI_DEEP_RESEARCH_ENABLED=false` + Service-Restart → keine neuen Jobs. Bereits pending Jobs laufen zu Ende (werden brav gepollt bis fertig), keine neuen kommen dazu.
Härter: direkte DB-Bereinigung —
```sql
DELETE FROM mana_ai.mission_research_jobs WHERE submitted_at < now() - interval '2 hours';
```
Die upstream-Tasks bleiben bei Google, aber wir lassen sie einfach laufen (Google berechnet sie trotzdem — aber das ist der Compute-Kosten-Sunk-Cost, nicht der Hebel).
## 7. Empfehlung
1. **Jetzt (erledigt, 2026-04-22):** Schritt 1 + 2 umgesetzt. Ein Pilot mit uns selbst (einem Test-User mit Founder-Tier und expliziter "deep research" Mission) kann ab sofort laufen. `MANA_AI_DEEP_RESEARCH_ENABLED=true` auf dem Mac-Mini setzen und eine Nightly-Mission anlegen.
2. **Nach 1 Woche Pilot:** Wenn Response-Qualität + Latenz überzeugen und kein größerer Parser-Fail auftritt → Founder-Tier öffnen (ENV-Flag bleibt, Opt-in per Mission-Wording).
3. **Nach 2 Wochen Pilot + Beta-Tier-Öffnung:** Schritt 3 (MCP-Server) M0-M1 starten — POC mit `search_notes` only + harter User-Gate.
4. **Nach Erfolg von M1:** M2-M4 iterativ. Public Rollout erst mit kompletter Audit-UX + dokumentiertem Privacy-Flow.
## Quellen
- [Google Blog — Deep Research Max: a step change for autonomous research agents](https://blog.google/innovation-and-ai/models-and-research/gemini-models/next-generation-gemini-deep-research/)
- [Google AI for Developers — Gemini Deep Research Agent docs](https://ai.google.dev/gemini-api/docs/deep-research)
- [Google AI for Developers — Gemini API changelog](https://ai.google.dev/gemini-api/docs/changelog)
- [VentureBeat — Google's new Deep Research and Deep Research Max agents can search the web and your private data](https://venturebeat.com/technology/googles-new-deep-research-and-deep-research-max-agents-can-search-the-web-and-your-private-data)
- [The Decoder — Google launches Deep Research and Deep Research Max agents to automate complex research](https://the-decoder.com/google-launches-deep-research-and-deep-research-max-agents-to-automate-complex-research/)
- [Testing Catalog — Google debuts Deep Research agents on AI Studio and APIs](https://www.testingcatalog.com/google-debuts-deep-research-agents-on-ai-studio-and-apis/)
- [H2S Media — Google Launches Deep Research Max, Its Most Powerful Autonomous Research Agent](https://www.how2shout.com/news/google-deep-research-max-gemini-api-autonomous-agent.html)
- [Model Context Protocol Specification (für Schritt 3)](https://modelcontextprotocol.io/specification)