--- name: integration-design description: Decide whether to embed a third-party tool in a display tab (EmbeddedTool) or link out with a summary panel (ExternalTool). Run before adding any integration, especially for experiment trackers, notebooks, CAD tools, dashboards, or anything with its own web UI. --- # Integration Design Every third-party tool Triptych touches hits the same fork: **embed it in a display tab, or link out and show a summary?** Trial 1 made the wrong call on Optuna Dashboard — embedded it, then needed four scripts + a `min-width: 1400px` iframe clamp to make it behave. The right call is decided up front, not discovered through residue. ## The decision table | Condition | Default | |---|---| | Tool renders well at panel size, has a clean iframe API, same-origin or permissive CORS | **Embed** | | Tool is the de-facto standard, users already have accounts, team-collaborative, or full-screen-assuming | **External** (link + API summary panel) | | Tool is desktop-only, has complex auth, or its UX fights the panel | **External** | | User explicitly prefers one | **User wins** | If two conditions conflict (e.g. "embeds cleanly" *and* "users already have accounts"), default to external. The cost of a bad embed (scripts, subprocess management, iframe clamps, auth proxies) is much higher than the cost of a summary panel. ## Walkthrough ### 1. Does the tool work in-panel at all? Open the tool in a browser at the Triptych display panel's typical width (800–1200px). If it says "this app requires at least N pixels wide" or the UI breaks visibly, you have one of: - An `ExternalTool` with a link-out - A redesigned workspace/ workspace addon (not a display) that *is* the full-width thing If the tool is usable but cramped, you can still embed — but the tool is telling you its design expects full-window use. ### 2. What does auth look like? - **No auth** (OSS tool, local subprocess): embedding is low-cost. Start subprocess with `EmbeddedTool.start()`. - **SSO / OAuth / cookie auth**: embedding fights the auth wall. Either the iframe gets redirected to a login page, or cross-origin cookies fail silently. `ExternalTool` is almost always correct here. - **API token**: ambiguous. The tool's UI probably needs the cookie auth path anyway. But the API can drive an `ExternalTool` summary panel cleanly. ### 3. What do users actually do with the tool? - **They open it to read a dashboard**: summary panel + link to full dashboard is usually better. They don't need the full UI to glance at the number. - **They interact deeply** (drag components, annotate, simulate): embed, if feasible. The interaction model loses too much value through an API summary. - **They collaborate with others in it** (W&B, Notion, Figma): external. Triptych is single-user; the tool's collaborative features are lost in an iframe anyway. ### 4. What's the update cadence? - **High-frequency (seconds)**: a live iframe isn't necessarily bad, but polling an API for a summary is usually fine at the cadences humans actually look at. - **On-demand**: no live update needed; summary panel refreshes when the agent asks. ### 5. Pick, implement, document Based on steps 1–4: - **EmbeddedTool**: subclass `integrations.EmbeddedTool`. Implement `start()` (idempotent), `stop()`, `is_running()`. Typically writes a display HTML file with `