feat: agent cloud execution via GitHub Codespaces

- github-auth.js: Device Flow OAuth (no backend/redirect)
- agent-cloud.js: Codespaces API adapter (create/exec/stop/cleanup)
- @cloud: yes/no field parsing + ☁️ toggle on Agent cards
- Cloud execution branch in generateAgentFlow()
- GitHub auth modal in modal-templates.js
- 5 new storage keys, Phase 3k loading, CSS styles
- docs/agent-cloud/ with implementation plan + walkthrough
- 20 Playwright tests (all passing)

Author: ijbo

README.md

@@ -38,7 +38,7 @@
 | **Security** | Content Security Policy (CSP), SRI integrity hashes, XSS sanitization (DOMPurify), ReDoS protection, Firestore write-token ownership, API keys via HTTP headers, postMessage origin validation, 8-char password minimum, sandboxed code execution, Cloudflare Turnstile CAPTCHA on email endpoint, automated security scanner (`scripts/security-check.sh`) with pre-commit integration |
 | **AI Document Tags** | `{{@AI:}}` text generation (`@think: Yes` for deep reasoning), `{{@Image:}}` image generation (Gemini Imagen), `{{@OCR:}}` image-to-text extraction (Text/Math/Table modes via Granite Docling 258M, Florence-2 230M, or GLM-OCR 1.5B, PDF page rendering via pdf.js), `{{@TTS:}}` text-to-speech playback (Kokoro TTS per card, language selector, ▶ Play / ⬇ Save WAV), `{{@STT:}}` speech-to-text dictation (engine selector: Whisper/Voxtral/Web Speech API, 11 languages, Record/Stop/Insert/Clear), `{{@Translate:}}` translation (target language selector, integrated TTS pronunciation, cloud model routing), `{{@Game:}}` game builder (AI-generated or pre-built, Canvas 2D/Three.js/P5.js, import/export HTML), `{{@Draw:}}` whiteboard (Excalidraw + Mermaid, AI diagram generation with per-card model selector + 🚀 Generate, robust JSON repair for local models, Insert/PNG/SVG export, 📚 Library Browser with 29 bundled packs in 6 categories) — `@` prefix syntax on all tag types + metadata fields (`@name`, `@use`, `@think`, `@search`, `@prompt`, `@step`, `@upload`, `@model`, `@engine`, `@lang`, `@prebuilt`); `@model:` field persists selected model per card with intelligent defaults (OCR→`granite-docling`, TTS→`kokoro-tts`, STT→`voxtral-stt`, Image→`imagen-ultra`); editable `@prompt:` textarea and `@step:` inputs in preview cards; description/prompt separation (bare text = label, `@prompt:` = AI instruction); 📎 image/PDF upload for multimodal vision analysis; per-card model selector with document-portable model persistence, concurrent block operations |
 | **🔌 API Calls** | `{{API:}}` REST API integration — GET/POST/PUT/DELETE methods, custom headers, JSON body, response stored in `$(api_varName)` variables; inline review panel; toolbar GET/POST buttons |
-| **🔗 Agent Flow** | `{{Agent:}}` multi-step pipeline — define Step 1/2/3, chain outputs, per-card model + search provider selector, live step status indicators (⏳/✅/❌), review combined output |
+| **🔗 Agent Flow** | `{{Agent:}}` multi-step pipeline — define Step 1/2/3, chain outputs, per-card model + search provider selector, live step status indicators (⏳/✅/❌), review combined output; `@cloud: yes` toggle routes execution to GitHub Codespaces (free ephemeral environments) via ☁️ button |
 | **🔍 Web Search** | Toggle web search for AI — 7 providers: DuckDuckGo (free), Brave Search, Serper.dev, Tavily (AI-optimized), Google CSE, Wikipedia, Wikidata; search results injected into LLM context; source citations in responses; per-agent-card search provider selector |
 | **🎮 Game Builder** | `{{@Game:}}` tag — AI-generated games (Canvas 2D / Three.js / P5.js) or instant pre-built games via `@prebuilt:` field (chess, snake, shooter, pong, breakout, maths quiz, hiragana, kana master); engine selector pills; per-card model picker; CDN URL normalizer for CSP compliance; auto model-ready check before generation; 📋 Import button for pasting/uploading external HTML game code with source viewer; 📥 Export as standalone HTML; ⛶ fullscreen; single-line field parsing; "Games for Kids" template with 8 playable games |
 | **🐧 Linux Terminal** | `{{Linux:}}` tag — two modes: (1) Terminal mode opens full Debian Linux ([WebVM](https://webvm.io)) in new window with `Packages:` field; (2) Compile & Run mode (`Language:` + `Script:`) compiles/executes 25+ languages (C++, Rust, Go, Java, Python, TypeScript, Kotlin, Scala…) via [Judge0 CE](https://ce.judge0.com) with inline output, execution time & memory stats |
@@ -523,6 +523,7 @@ TextAgent has undergone significant evolution since its inception. What started
 
 | Date | Commits | Feature / Update |
 |------|---------|-----------------:|
+| **2026-03-19** | | ☁️ **Agent Cloud Execution** — new `@cloud: yes` field and ☁️ toggle button on Agent Flow cards to route step execution to free GitHub Codespaces; `github-auth.js` Device Flow OAuth module (no backend/redirect needed); `agent-cloud.js` Codespaces API adapter (create/exec/stop/cleanup with idle timeout and custom endpoint fallback); GitHub auth modal reusing `ai-consent-modal` layout; 5 new storage keys; Phase 3k module loading; CSS for cloud toggle + device code UI; [implementation plan](docs/agent-cloud/implementation_plan.md) and [walkthrough](docs/agent-cloud/walkthrough.md); 20 new Playwright tests |
 | **2026-03-18** | | 🧪 **Test Coverage Expansion** — 51 new Playwright tests across 8 new spec files for previously untested features: Help Mode (toggle, popover, shortcuts, demo, Escape, click interception), Page View (enter/exit A4, page frames, counter, zoom), Table Tools (container, toolbar, badges, editable cells, tiny table skip), API Tag (parsing, config, fenced block ignore, card rendering), Linux Tag (terminal/script modes, Stdin, fenced ignore, cards), Template System (modal open/close, categories, search, card rendering), Inline Rename (title chip, filename, QAB, modal), Presentation Mode (PPT switching, slide content, view mode bar); total test count 521 → 572 |
 | **2026-03-18** | | 🛡️ **Turnstile CSP Fix** — added `https://challenges.cloudflare.com` to CSP `script-src`, `style-src`, `img-src`, and `frame-src` directives to allow Cloudflare Turnstile CAPTCHA widget to fully load and render; changed referrer policy from `no-referrer` to `strict-origin-when-cross-origin` so Turnstile can verify the hostname for CAPTCHA validation |
 | **2026-03-18** | | ✏️ **Inline File Rename** — clickable document title chip in header showing active file name (without `.md`); click to open rename modal with name pre-selected; title chip also added to Quick Action Bar (collapsed header) for always-visible rename access; both chips auto-sync on file switch, rename, or create; pencil icon appears on hover; responsive hiding on narrow screens (main header) with QAB always visible |

changelogs/CHANGELOG-agent-cloud.md

@@ -0,0 +1,67 @@
+# Agent Cloud Execution — GitHub Codespaces Integration
+
+- Added GitHub Device Flow OAuth module (`github-auth.js`) for zero-redirect, no-backend authentication
+- Added Codespaces API adapter (`agent-cloud.js`) for creating, executing commands on, and managing ephemeral Codespaces
+- Added GitHub auth modal to `modal-templates.js` reusing existing `ai-consent-modal` layout classes
+- Added `@cloud: yes/no` field parsing in `ai-docgen.js` (alongside existing `@think:`, `@search:` fields)
+- Added ☁️ cloud toggle button to Agent Flow card header (gated: opens GitHub auth if not signed in)
+- Added cloud execution branch in `ai-docgen-generate.js` — routes Agent Flow steps to Codespaces when `@cloud: yes`
+- Added Phase 3k module loading in `src/main.js` (after Draw Component)
+- Added 5 new localStorage keys: `GITHUB_TOKEN`, `GITHUB_USER`, `AGENT_PROVIDER`, `AGENT_CODESPACE_ID`, `AGENT_CUSTOM_URL`
+- Added CSS for cloud toggle active state, GitHub device code display, and spin animation
+- Added 20 Playwright tests covering storage keys, auth modal, module APIs, `@cloud:` parsing, and toggle UI
+
+---
+
+## Summary
+
+Integrates external agent execution (OpenClaw/OpenFang) via GitHub Codespaces into TextAgent's existing Agent Flow system. Users click ☁️ on any Agent card to route step execution to a free cloud Codespace instead of the local LLM. Authentication uses GitHub's Device Flow (no backend needed). Requires a GitHub OAuth App Client ID and a template repository to be configured before use.
+
+---
+
+## 1. GitHub Device Flow OAuth
+**Files:** `js/github-auth.js` (NEW), `js/modal-templates.js`
+**What:** IIFE module implementing GitHub's Device Flow: request device code → user enters code at github.com → poll for token → store in localStorage. Modal HTML injected via `modal-templates.js` reusing `ai-consent-modal` / `ai-apikey-content` classes.
+**Impact:** Users can sign into GitHub directly from TextAgent without any backend, redirect URL, or client secret. Works from any origin including `file://`.
+
+## 2. Codespaces API Adapter
+**Files:** `js/agent-cloud.js` (NEW)
+**What:** IIFE module exposing `M.agentCloud` with `run()`, `stop()`, `cleanup()`, `listRunning()`, `getStatus()`. Creates or reuses ephemeral Codespaces, executes commands via the template repo's HTTP API, auto-stops after 5 min idle. Includes custom endpoint fallback for E2B/Daytona.
+**Impact:** Agent Flow steps can now execute arbitrary commands on cloud infrastructure instead of being limited to local LLM text generation.
+
+## 3. Agent Flow `@cloud:` Field + Toggle
+**Files:** `js/ai-docgen.js`, `js/ai-docgen-generate.js`
+**What:** 3 edits to `ai-docgen.js`: regex parsing for `@cloud: yes/no`, ☁️ button in Agent card header, click handler that gates on auth. 1 edit to `ai-docgen-generate.js`: cloud execution branch in `generateAgentFlow()` that calls `M.agentCloud.run()` when `block.cloud` is true.
+**Impact:** Users can toggle cloud execution per Agent card. The `@cloud: yes` directive persists in the markdown tag text.
+
+## 4. Module Loading & Storage
+**Files:** `src/main.js`, `js/storage-keys.js`
+**What:** Added Phase 3k (`github-auth.js` + `agent-cloud.js`) after the Draw Component in the dynamic import chain. Added 5 new `textagent-*` prefixed keys to the central key registry.
+**Impact:** Modules load automatically in correct dependency order. Settings persist across sessions.
+
+## 5. CSS Styling
+**Files:** `css/ai-docgen.css`
+**What:** Cloud toggle `.active` state (blue accent), GitHub device code display (monospace, large, selectable), device flow instructions, spin animation for waiting indicator.
+**Impact:** Consistent visual styling with existing think/search toggles. Dark and light theme support.
+
+## 6. Automated Tests
+**Files:** `tests/feature/agent-cloud.spec.js` (NEW)
+**What:** 20 Playwright tests: storage key presence, GitHub auth modal DOM/visibility, `githubAuth` module API surface, `agentCloud` module API surface, `@cloud:` field parsing (yes/no/default/stripping), cloud toggle rendering and auth gate.
+**Impact:** Full regression coverage for the new feature. All 20 tests pass.
+
+---
+
+## Files Changed (10 total)
+
+| File | Lines Changed | Type |
+|------|:---:|------|
+| `js/github-auth.js` | +215 | New — GitHub Device Flow OAuth |
+| `js/agent-cloud.js` | +270 | New — Codespaces API adapter |
+| `tests/feature/agent-cloud.spec.js` | +295 | New — 20 Playwright tests |
+| `js/modal-templates.js` | +50 | GitHub auth modal HTML |
+| `js/ai-docgen.js` | +30 | @cloud: parsing, ☁️ toggle, handler |
+| `js/ai-docgen-generate.js` | +17 | Cloud execution branch |
+| `js/storage-keys.js` | +7 | 5 agent execution keys |
+| `src/main.js` | +4 | Phase 3k loading |
+| `css/ai-docgen.css` | +76 | Cloud toggle + device code CSS |
+| `changelogs/CHANGELOG-agent-cloud.md` | +57 | This changelog |

css/ai-docgen.css

@@ -3033,4 +3033,80 @@
 [data-theme="light"] .ai-card-upload-thumb {
     border-color: rgba(37, 99, 235, 0.25);
     background: rgba(0, 0, 0, 0.05);
+}
+
+/* --- Cloud Toggle Button (Agent Card) --- */
+.ai-cloud-toggle.active {
+    background: rgba(56, 139, 253, 0.2) !important;
+    border-color: rgba(56, 139, 253, 0.4) !important;
+    color: #58a6ff !important;
+    box-shadow: 0 0 6px rgba(56, 139, 253, 0.15);
+}
+
+.ai-cloud-toggle.active:hover {
+    background: rgba(56, 139, 253, 0.3) !important;
+}
+
+[data-theme="light"] .ai-cloud-toggle.active {
+    background: rgba(37, 99, 235, 0.12) !important;
+    border-color: rgba(37, 99, 235, 0.35) !important;
+    color: #2563eb !important;
+}
+
+/* --- GitHub Device Code UI --- */
+.github-device-code {
+    font-family: 'SF Mono', 'Cascadia Code', 'Consolas', monospace;
+    font-size: 1.8rem;
+    font-weight: 700;
+    letter-spacing: 0.3em;
+    text-align: center;
+    padding: 16px;
+    background: rgba(110, 118, 129, 0.1);
+    border: 1px solid rgba(110, 118, 129, 0.2);
+    border-radius: 8px;
+    margin: 12px 0;
+    color: var(--color-fg-default, #e6edf3);
+    user-select: all;
+    cursor: text;
+}
+
+[data-theme="light"] .github-device-code {
+    background: rgba(0, 0, 0, 0.04);
+    border-color: rgba(0, 0, 0, 0.12);
+    color: #24292e;
+}
+
+.github-device-instructions {
+    font-size: 0.9em;
+    color: var(--color-fg-muted, #8b949e);
+    margin-bottom: 4px;
+}
+
+.github-device-instructions a {
+    color: #58a6ff;
+    font-weight: 600;
+}
+
+.github-device-waiting {
+    font-size: 0.85em;
+    color: var(--color-fg-muted, #8b949e);
+    text-align: center;
+}
+
+.github-user-info {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 8px 0;
+}
+
+/* Spin animation for waiting indicator */
+@keyframes ai-spin {
+    from { transform: rotate(0deg); }
+    to { transform: rotate(360deg); }
+}
+
+.ai-spin {
+    display: inline-block;
+    animation: ai-spin 1s linear infinite;
 }