Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

feat(mcp): simplify ChatGPT UI to Block and Page

Rahman2a66c0c6a847
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index c97d317a..41a7c772 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -118,20 +118,28 @@ through the app catch-all.
### 4.1 ChatGPT as an MSO presentation target
The web catch-all remains the authenticated cockpit route. ChatGPT does **not** frame that cockpit.
-Instead `render_mso_surface` binds the versioned MCP App resource `ui://mso/surface-v5.html`, which
-implements a smaller presentation router for `/`, `/monitor`, `/project`, `/diff`, `/browser` and
-`/apps/<reviewed-id>`. Native Surface views call the same bounded MSO tools; reviewed app demos may
-use a nested iframe only when their exact HTTPS origin exists in the code-owned Surface catalog and
-the MCP resource CSP `frameDomains`. Anti-frame apps stay on the remote-browser seam. `project_get`,
-`project_diff`, and `vps_status` remain pure data tools with no UI template; only `render_mso_surface`
-owns the general-purpose Surface resource, while `workflow_start` retains its dedicated progress card.
-
-This trust catalog is deliberately separate from Store/runtime `AppManifest` data. A locally installed
-`runtime:"html"` app or HTML widget is user-controlled presentation data and cannot grant itself a
-ChatGPT nested-frame origin. `srcDoc` HTML remains opaque-origin sandboxed, the MCP widget stays on
-`mso-ui.rahmanef.com`, and the authenticated `mso.rahmanef.com` cockpit retains its deny-framing
-headers. The split prevents convenient HTML/runtime extensibility from becoming a CSP privilege
-escalation path.
+MSO exposes exactly two user-visible MCP App classes instead:
+
+- `render_mso_block` binds `ui://mso/block-v1.html` for compact validation, action buttons, and
+ CRUD input-output. A button returns a user-approved follow-up message; it does not execute a
+ mutation inside the widget, so ordinary scope, approval, audit, and workflow rules still apply.
+- `render_mso_page` binds `ui://mso/page-v1.html` for native `/`, `/monitor`, `/project`, `/diff`,
+ `/browser`, and `/apps/<reviewed-id>` views. Native Page views call the same bounded MSO tools.
+
+`workflow_start` is orchestration-only and headless: it still owns workflow isolation, skill/recipe
+lookup, collision detection, tracing, evidence, and learning, but no longer binds a UI resource.
+`project_get`, `project_diff`, and `vps_status` likewise remain pure data tools. The previous
+`render_mso_surface` and `workflow_status` actions are app-only compatibility shims for cached
+widgets; the previous resource URIs remain readable aliases but are not advertised.
+
+Reviewed Page apps may use a nested iframe only when their exact HTTPS origin exists in the
+code-owned Page catalog and the MCP resource CSP `frameDomains`; anti-frame apps stay on the
+remote-browser seam. This trust catalog is deliberately separate from Store/runtime `AppManifest`
+data. A locally installed `runtime:"html"` app or HTML widget is user-controlled presentation data
+and cannot grant itself a ChatGPT nested-frame origin. `srcDoc` HTML remains opaque-origin
+sandboxed, the MCP widget stays on `mso-ui.rahmanef.com`, and the authenticated
+`mso.rahmanef.com` cockpit retains its deny-framing headers. The split prevents convenient
+HTML/runtime extensibility from becoming a CSP privilege-escalation path.
## 5. Host API and filesystem model
@@ -272,6 +280,6 @@ When sources disagree, use this order:
selected machine-verifiable facts, comparison evidence and source-review freshness so common drift becomes a gate failure instead of a
future archaeology task.
-### ChatGPT MSO Surface trust boundary
+### ChatGPT MSO Page trust boundary
-Each MSO connector/server scope owns its own Surface catalog. Core MSO Surface code must not import project identities or trusted frame origins from another server scope. The current Fresh 3/VPSKU app target is Play Together (`game.rahmanef.com`). Only its dedicated `/embed` namespace opts into framing by `mso-ui.rahmanef.com`; the normal Play Together shell remains anti-frame. MSO allowlists the exact game origin and enforces the `/embed` prefix in the browser-side Surface renderer. Any future iframe origin requires an explicit review and resource-URI/toolset bump.
+Each MSO connector/server scope owns its own Page app catalog. Core MSO Page code must not import project identities or trusted frame origins from another server scope. The current Fresh 3/VPSKU app target is Play Together (`game.rahmanef.com`). Only its dedicated `/embed` namespace opts into framing by `mso-ui.rahmanef.com`; the normal Play Together shell remains anti-frame. MSO allowlists the exact game origin and enforces the `/embed` prefix in the browser-side Page renderer. Any future iframe origin requires an explicit review and resource-URI/toolset bump. The Block resource has no frame domains.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index ec4b30c9..d42c7b94 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,6 +8,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.
**Added**
+- `mcp` simplify ChatGPT UI to Block and Page
- `assistant` turn Alfa into MSO cockpit
**Fixed**
diff --git a/docs/CHATGPT-PLUGIN.md b/docs/CHATGPT-PLUGIN.md
index 7d0a909e..90f02268 100644
--- a/docs/CHATGPT-PLUGIN.md
+++ b/docs/CHATGPT-PLUGIN.md
@@ -27,8 +27,8 @@ ChatGPT
├─ explicit bounded infrastructure operations
├─ project snapshot / diff / knowledge / project-agent tasks
├─ Convex status + dynamic Convex MCP schemas/calls
- ├─ MCP Apps UI for workflow, project, diff and VPS
- ├─ universal MSO Surface + reviewed live app demos
+ ├─ explicit MCP Block for validation/action/CRUD input-output
+ ├─ full MSO Page + reviewed dev/preview/production app embeds
└─ dynamic project MCP/function seams for project-owned tools
```
@@ -56,7 +56,7 @@ The restored Original MSO operator primitives (`sys_*`, `fs_usage` + full bounde
Project-owned MCP names and Convex's own dynamic schemas still load on demand through `project_mcp_tools` / `project_mcp_call` and `project_database_tools` / `project_database_call`. That is how MSO keeps a bounded static model profile instead of copying every downstream provider/project action into ChatGPT.
-`render_mso_surface` is the presentation bridge for ChatGPT-as-an-MSO-shell. It accepts only MSO-style routes and a server-reviewed app id; arbitrary HTML and external URL inputs are not part of its schema. `mso_surface_apps_list` exposes only the public reviewed catalog. Direct nested frames are exact-origin allowlisted in the MCP App resource CSP, while anti-frame applications remain remote-browser candidates. User-installed runtime HTML apps do not inherit this trust automatically.
+ChatGPT presentation is explicit rather than attached to every operation. `workflow_start` is headless. `render_mso_block` opens the compact validation/action/CRUD component and accepts only bounded fields, checks, outputs, and follow-up actions; a button cannot execute a mutation inside the widget. `render_mso_page` opens native MSO views or a code-reviewed development/preview/production app. It accepts only MSO-style routes and server-owned app ids, never arbitrary HTML or an external URL. `mso_surface_apps_list` exposes the reviewed Page catalog. Direct nested frames are exact-origin allowlisted in the Page CSP, while anti-frame applications remain remote-browser candidates. User-installed runtime HTML apps do not inherit this trust automatically. `render_mso_surface` and `workflow_status` remain app-only compatibility shims for cached clients.
### Structured-result contract
@@ -149,7 +149,7 @@ MSO uses Streamable HTTP JSON-RPC over `POST /mcp`.
4. Choose OAuth and complete the MSO consent flow on an approved owner device.
5. Select the lowest useful MSO tier.
6. Run **Scan Tools / Refresh** in ChatGPT.
-7. Verify that the action snapshot corresponds to the 64-tool transport profile (63 model actions + app-only `workflow_status`) in the generated catalog.
+7. Verify that the action snapshot corresponds to the 66-tool transport profile (64 model-visible actions + app-only `workflow_status` and `render_mso_surface`) in the generated catalog.
8. Start a new chat when testing a newly scanned draft/action snapshot.
After a schema/profile change, changing production code alone does not replace ChatGPT's frozen action snapshot. Refresh/re-scan (or recreate/republish where the workspace UI requires it) after deployment.
@@ -180,5 +180,5 @@ The live diagnostic `GET /mcp` returns both `toolset` (full MSO) and `chatgptToo
- Remote HTTP project MCP calls retain MSO's public-address / SSRF / DNS-rebinding guard.
- Tool hiding is not a substitute for scope checks; list-time and call-time scope enforcement both remain mandatory.
- Hidden ChatGPT transcript, private chain-of-thought and credentials are never copied into Local Agent/project MCP messages.
-- MSO Surface never accepts raw HTML/arbitrary URL input; nested iframe origins are code-reviewed, exact-origin CSP entries and revalidated in the widget.
+- MSO Block accepts only bounded fields/checks/outputs/actions and never executes a mutation directly; MSO Page never accepts raw HTML/arbitrary URL input, and nested iframe origins are code-reviewed, exact-origin CSP entries revalidated in the widget.
- The authenticated MSO cockpit stays non-frameable, and user-installed HTML/runtime manifests cannot promote themselves into the ChatGPT frame allowlist.
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 33118c40..2f04bb1b 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -1,4 +1,5 @@
# mso — Progress Log
+- **Headless workflows + two-surface MCP UI contract (2026-09-04):** MCP server `1.10.0` / toolset `2026.09.04.6` removes the automatic UI binding from `workflow_start`: orchestration, collision checks, tracing, evidence, and learning continue in the background without consuming the answer with a progress card. ChatGPT now has exactly two canonical MCP App resources: `ui://mso/block-v1.html` through `render_mso_block` for compact validation/action/CRUD input-output, and `ui://mso/page-v1.html` through `render_mso_page` for native operator views plus reviewed development/preview/production embeds. Block buttons send a user-approved follow-up and never execute mutations inside the widget, preserving normal scope, approval, audit, and workflow boundaries. The prior workflow/surface URIs remain non-advertised read aliases, while `workflow_status` and `render_mso_surface` remain app-only compatibility shims for cached clients. The ChatGPT transport profile is 66 tools: 64 model-visible actions (35 read / 17 write / 12 exec) plus two app-only shims; the full catalog is 90. Only Block and Page advertise a resource URI.
- **Local release audit timeout hardening (2026-09-04):** the tolerant pre-push dependency audit now caps `bun audit --json` at 15 seconds. A registry timeout is reported and skipped only in the local gate, matching its existing network-tolerant policy; CI remains the fail-closed dependency-audit authority. This prevents a slow registry request from holding GitHub's pre-push SSH session open for minutes and failing the otherwise-green release with a transport/SIGPIPE-style exit.
- **MCP Apps CSP metadata dedup / Surface v5 (2026-09-04):** MCP server `1.9.4` / toolset `2026.09.04.5` moves all standard widget CSP fields to the preferred `_meta.ui.csp` surface and leaves legacy `openai/widgetCSP` with only `redirect_domains` for `Open in MSO`. Workflow/Surface resources are cache-busted to `workflow-progress-v3` and `surface-v5`; the reviewed Play Together iframe remains exact-origin under `/embed`, so one external-iframe review advisory is expected from `ui.csp.frameDomains`. Scanner-facing Surface metadata explicitly names `/apps/play-together` and has a regression guard against cross-scope app examples.
- **MCP Apps presentation unification / Surface v4 (2026-09-04):** MCP server `1.9.3` / toolset `2026.09.04.4` retires the specialized `project-status-v2`, `project-diff-v2`, and `vps-status-v2` resources. `project_get`, `project_diff`, and `vps_status` are pure data tools again; `ui://mso/surface-v4.html` is the only general-purpose UI and uses the portable MCP Apps `tools/call` bridge for native monitor/project/diff views. `workflow-progress-v2` remains intentionally separate for live workflow polling. Play Together keeps the exact `game.rahmanef.com/embed` frame boundary, so the external-iframe review advisory remains expected only for the universal Surface.
diff --git a/docs/TESTING-HANDOFF.md b/docs/TESTING-HANDOFF.md
index 579c5d2a..920e8b97 100644
--- a/docs/TESTING-HANDOFF.md
+++ b/docs/TESTING-HANDOFF.md
@@ -5,12 +5,12 @@ Update this file at the end of every manual or automated test session. Keep it f
## Current status
-The current release target is **MSO CLI 1.12.1**, MCP server `1.9.4`, toolset `2026.09.04.5`; use `mso --version` plus `/api/health` for the exact Git build because documentation-only release commits also advance that identity. The v1.10/v1.11 findings and the v1.12 sectioned-terminal/recoverable-error work below are resolved and retained as historical test evidence. Do not re-open a resolved finding from prose alone: reproduce it against the current build first. There is no known 1.12 release blocker in this handoff.
+The current release target is **MSO CLI 1.12.1**, MCP server `1.10.0`, toolset `2026.09.04.6`; use `mso --version` plus `/api/health` for the exact Git build because documentation-only release commits also advance that identity. The v1.10/v1.11 findings and the v1.12 sectioned-terminal/recoverable-error work below are resolved and retained as historical test evidence. Do not re-open a resolved finding from prose alone: reproduce it against the current build first. There is no known 1.12 release blocker in this handoff.
Current verified behavior:
- **2026-09-04 Cognitive Runtime public-claim audit:** source/main/origin + loopback/public production were revalidated on the latest concurrent baseline. Fresh reruns pass `bench:cognitive`, `bench:memory`, P9 200-correction calibration, P10 lifecycle, and P10 retrieval calibration. Current deterministic evidence: 100% required-tool recall, 96.6% active-schema reduction, memory 8/8, P9 6/6, P10 lifecycle 8/8, lexical/local-semantic 4/6 vs 3/6, graph fixture 3/3. Canonical raw comparison artifacts were re-hashed: P6 `e0b5e1e30a9f1e5b34624e42d4bb5195792e50129b74de7d4006906a99716ba5`, P7 two-run `a0c12961d142420f6ac334ff021bde7ab82faa89f9294107d3bd46823606a530`, P8 three-run `f70e2f5e8132f0808976ed69e2cb6769d2cec861d58612a8cca2ef5d80a7d838`, P8 cache `b4a2b1be5dc6edfb2ce8282eae64e3a4fc206cd043ecb825a1eae6a617c9f871`. The canonical P7 file is `mso-p7-repeat-full-2x9.json`; the similarly named `mso-p7-repeat-full-2runs.json` is a different, non-canonical run. Recomputed P7+P8 evidence is 5/5 perfect for both MSO and Hermes with 74.7% fewer normalized tokens/attempt, 12.8% lower mean average latency, and 34.1% lower mean per-run p50 for MSO on that exact matched nine-scenario corpus. P4/P5 exact numeric tables are historical-only because their exact raw artifacts were not independently revalidated in this audit. Cost/cache/OpenClaw remain unranked. Tool Forge source/non-Docker tests pass, but the local Forge Docker image was absent, so three Docker-only tests were correctly skipped and executable evaluation fails closed until explicitly provisioned.
-- Fresh 3 current MCP contract: server `1.9.4` / toolset `2026.09.04.5`; ChatGPT receives **64 transport tools = 63 model/operator actions (34 read / 17 write / 12 exec) + app-only `workflow_status`**, while the full transport catalog is 88 tools / 87 model tools. Every ChatGPT action advertises `outputSchema`, the dedicated MCP Apps widget origin is `https://mso-ui.rahmanef.com`, and five official digest-verified Skills are exposed through the MCP Skills/resource extension. Exactly two MCP App resources are published: dedicated `ui://mso/workflow-progress-v3.html` plus universal `ui://mso/surface-v5.html`. `project_get`, `project_diff`, and `vps_status` are pure data tools with no UI template; Surface native views refresh them through MCP Apps `tools/call`. The Surface accepts no raw HTML/arbitrary URL; its only frame domain is `https://game.rahmanef.com`, and every Play Together iframe URL must remain under `/embed`. The normal Play Together shell stays anti-frame, while the dedicated embed namespace allows only `mso-ui.rahmanef.com`. Other MSO server scopes are not copied into this catalog.
-- MCP App navigation acceptance: a ChatGPT-opened root URL carrying `redirectUrl=https://chatgpt.com/c/...` must 307 to `/assistant/mcp`, then authenticated browser E2E must show the Alfa `Activity & Runs` view. The dedicated workflow card targets `/assistant/mcp`; VPS/project/diff are native routes inside universal Surface v5 rather than independent widgets. Surface v5 plus workflow-progress-v3 are cache-busting resource URI changes, so ChatGPT must re-scan Fresh 3 after deployment.
+- Fresh 3 current MCP contract: server `1.10.0` / toolset `2026.09.04.6`; ChatGPT receives **66 transport tools = 64 model-visible actions (35 read / 17 write / 12 exec) + app-only `workflow_status` and `render_mso_surface` compatibility shims**, while the full transport catalog is 90 tools. Every ChatGPT action advertises `outputSchema`, and the dedicated MCP Apps origin remains `https://mso-ui.rahmanef.com`. Exactly two canonical resources are published: `ui://mso/block-v1.html` for validation/action/CRUD input-output and `ui://mso/page-v1.html` for native views plus reviewed dev/preview/prod embeds. `workflow_start` is headless and has no UI template. Only `render_mso_block` and `render_mso_page` bind resources. Previous workflow/surface URIs remain readable but unlisted; the two app-only actions keep cached clients functional. Page framing remains exact-origin under `https://game.rahmanef.com/embed`, while Block has no frame domains and cannot execute a mutation directly.
+- MCP App acceptance: starting a workflow must produce structured workflow identity without opening an App. A Block must render bounded validation/CRUD data and return a user-approved follow-up when its action is pressed; it must not call a mutation itself. A Page must render native `/monitor`/`/project`/`/diff` views through `tools/call` and frame Play Together only from `https://game.rahmanef.com/embed`. The old workflow/surface URIs must resolve only as non-advertised compatibility aliases. Block v1 and Page v1 are cache-busting resource changes, so ChatGPT must re-scan Fresh 3 after deployment.
- Alfa Cockpit acceptance: Assistant → Chat shows a compact project/model/activity bar; Cockpit opens as a desktop panel and mobile drawer; project search can select a project outside the first bounded page; selected project metadata reaches the next Alfa system prompt but raw `KNOWLEDGE.md`/repo-memory bodies do not; private typed-memory keys/values render as `Private memory`; Host Skills lazy-load from `/api/skills`; model switch stays within the configured provider; Activity & Runs shows local Alfa tool state alongside MCP workflow activity without treating the browser run as MCP `workflow_finish`.
- Alfa Automation acceptance: a saved recipe's Run action switches to its configured persona and submits the ordered recipe through normal Alfa execution. Read steps may execute directly; write/exec steps must still park on the existing approval card. Playbook starter prompts appear as bounded empty-chat quick actions.
diff --git a/docs/generated/MCP-CATALOG.md b/docs/generated/MCP-CATALOG.md
index 3530d52b..b9310206 100644
--- a/docs/generated/MCP-CATALOG.md
+++ b/docs/generated/MCP-CATALOG.md
@@ -4,21 +4,21 @@
## Full MSO catalog
-<!-- mcp-toolset: server=1.9.4 version=2026.09.04.5 tools=87 read=43 write=25 exec=19 -->
+<!-- mcp-toolset: server=1.10.0 version=2026.09.04.6 tools=88 read=44 write=25 exec=19 -->
| Fact | Current source value |
|---|---:|
-| MCP server | `1.9.4` |
-| Toolset | `2026.09.04.5` |
-| Toolset changed at | `2026-09-04T01:36:00Z` |
-| Transport tools | **88** |
-| Model/operator tools | **87** |
-| Read | **43** |
+| MCP server | `1.10.0` |
+| Toolset | `2026.09.04.6` |
+| Toolset changed at | `2026-09-04T09:36:00Z` |
+| Transport tools | **90** |
+| Model/operator tools | **88** |
+| Read | **44** |
| Write | **25** |
| Exec | **19** |
-| App-only bridges | **1** |
+| App-only bridges | **2** |
-### Read (43)
+### Read (44)
- `a2a_agent_discover`
- `a2a_agents_list`
@@ -54,7 +54,8 @@
- `project_memory_search`
- `projects_list`
- `read_pipeline`
-- `render_mso_surface`
+- `render_mso_block`
+- `render_mso_page`
- `screen_capture`
- `skills_list`
- `skills_read`
@@ -114,26 +115,27 @@
- `tool_forge_evaluate`
- `tool_forge_promote`
-### App-only bridges (1)
+### App-only bridges (2)
+- `render_mso_surface`
- `workflow_status`
## ChatGPT static profile
-<!-- mcp-chatgpt-profile: server=1.9.4 version=2026.09.04.5 tools=63 read=34 write=17 exec=12 app-only=1 total=64 -->
+<!-- mcp-chatgpt-profile: server=1.10.0 version=2026.09.04.6 tools=64 read=35 write=17 exec=12 app-only=2 total=66 -->
The ChatGPT profile is a fail-closed static projection defined by `CHATGPT_TOOL_NAMES`. OAuth scope is still enforced independently; project-owned MCP tool names remain dynamic data behind the generic project bridge.
| Fact | Current source value |
|---|---:|
-| ChatGPT transport tools | **64** |
-| ChatGPT model/operator tools | **63** |
-| Read | **34** |
+| ChatGPT transport tools | **66** |
+| ChatGPT model/operator tools | **64** |
+| Read | **35** |
| Write | **17** |
| Exec | **12** |
-| App-only bridges | **1** |
+| App-only bridges | **2** |
-### ChatGPT read (34)
+### ChatGPT read (35)
- `agent_session_current`
- `apps_list`
@@ -161,7 +163,8 @@ The ChatGPT profile is a fail-closed static projection defined by `CHATGPT_TOOL_
- `project_knowledge_get`
- `projects_list`
- `read_pipeline`
-- `render_mso_surface`
+- `render_mso_block`
+- `render_mso_page`
- `screen_capture`
- `skills_list`
- `skills_read`
@@ -205,6 +208,7 @@ The ChatGPT profile is a fail-closed static projection defined by `CHATGPT_TOOL_
- `project_mcp_call`
- `project_mcp_tools`
-### ChatGPT app-only bridges (1)
+### ChatGPT app-only bridges (2)
+- `render_mso_surface`
- `workflow_status`
diff --git a/docs/integrations/CHATGPT-UI.md b/docs/integrations/CHATGPT-UI.md
index 2341a3bc..04c72ca5 100644
--- a/docs/integrations/CHATGPT-UI.md
+++ b/docs/integrations/CHATGPT-UI.md
@@ -1,112 +1,133 @@
# ChatGPT MCP App UI
-MSO renders first-party interactive operator cards inside ChatGPT while keeping JSON/text results as the portable fallback for MCP clients that do not implement MCP Apps.
+MSO treats ChatGPT as a presentation target without turning every tool call into a widget. JSON/text results remain the portable fallback for MCP clients that do not implement MCP Apps.
-## Contract
+## Product contract: Block or Page
-A normal tool result cannot create an inline application by returning arbitrary HTML. MSO exposes the MCP Apps contracts explicitly:
+The user-visible contract has exactly two canonical MCP App resources:
-1. `resources/list` / `resources/read` expose `ui://…` resources with `text/html;profile=mcp-app`.
-2. Only render-entry tools bind a resource with `_meta.ui.resourceUri`; data tools return structured results without templates. `workflow_start` owns the dedicated progress resource and `render_mso_surface` owns the general-purpose Surface. The OpenAI `outputTemplate` alias remains only on those render entries for compatibility.
-3. Every ChatGPT action declares `outputSchema`. UI/critical tools use typed projections; other actions use the shared bounded `{ result }` structured envelope. Generic MCP clients keep their historical text fallback unless an explicit output schema exists.
-4. Sandboxed widgets read tool results from the MCP Apps bridge and use standard `tools/call` for data refreshes. ChatGPT-only extensions remain feature-detected for display mode, widget state, and `openExternal`.
+| Surface | Entry tool | Resource | Intended use |
+| --- | --- | --- | --- |
+| **Block** | `render_mso_block` | `ui://mso/block-v1.html` | Compact validation, action buttons, and CRUD input-output |
+| **Page** | `render_mso_page` | `ui://mso/page-v1.html` | Full native operator views and reviewed development, preview, or production app embeds |
+
+`workflow_start` is now headless. It remains the required orchestration bootstrap for multi-step work, including skill/recipe lookup, collision checks, workflow isolation, tracing, evidence, and learning, but it has no `_meta.ui.resourceUri` and no `openai/outputTemplate`. Starting background work therefore does not consume the answer with an unrelated workflow card.
+
+A normal data/action tool also remains headless unless its result genuinely needs one of the two explicit presentation tools. `project_get`, `project_diff`, and `vps_status`, for example, keep structured outputs with no UI binding; the Page may call them through the standard MCP Apps `tools/call` bridge when it needs a native view.
Official references:
- <https://developers.openai.com/plugins/build/chatgpt-ui>
- <https://developers.openai.com/plugins/reference>
-## MSO resources
+## Block
-| Experience | Entry tool | Resource | Refresh behavior |
-| --- | --- | --- | --- |
-| Workflow progress | `workflow_start` | `ui://mso/workflow-progress-v3.html` | app-only `workflow_status` |
-| Universal MSO Surface | `render_mso_surface` | `ui://mso/surface-v5.html` | `/monitor`, `/project`, and `/diff` call pure data tools via `tools/call`; Play Together uses its reviewed exact-origin `/embed` frame boundary |
+`render_mso_block` accepts bounded structured data rather than HTML:
-Source boundaries:
+- `kind`: `validation`, `crud`, or `action`;
+- title, description, and neutral/pending/success/warning/error status;
+- editable or read-only fields (`text`, `number`, `email`, `url`, `textarea`, `boolean`);
+- pass/warn/fail/info checks;
+- scalar output rows;
+- up to eight user-facing action buttons.
-| Contract | MSO source |
-| --- | --- |
-| Resource registry / workflow UI | `lib/mcp/ui-resources.ts` |
-| Universal Surface resource/runtime | `lib/mcp/ui-surface.ts`, `lib/mcp/ui-surface-script.ts`, `lib/mcp/ui-surface-style.ts` |
-| Surface security catalog/router | `lib/mcp/surface-catalog.ts`, `lib/mcp/tools-surface.ts` |
-| Resource capability / RPC | `lib/mcp/dispatch.ts` |
-| Workflow structured schema | `lib/mcp/tools-workflow-start.ts`, `lib/mcp/tools-workflow-lifecycle.ts` |
-| Project/diff structured schemas | `lib/mcp/tools-project-experience.ts` |
-| VPS structured schema | `lib/mcp/tools-operator-dashboard.ts` |
-| Shared executable capability schema | `lib/capabilities/tool.ts` (`lib/mcp/tool-kit.ts` is the compatibility adapter) |
-| MCP descriptor/profile contract | `lib/mcp/tool-contract.ts` |
-| Toolset signature | `lib/mcp/toolset.ts` |
-| Tests | `lib/mcp/ui-resources.test.ts` |
+A Block button does **not** call a write/exec tool from inside the widget. After a real user click it sends a bounded follow-up message containing the action id and current field values. ChatGPT must then continue through the ordinary MCP tool path, so OAuth scope, argument validation, approval, rate limit, audit, workflow correlation, and destructive-operation rules remain authoritative. An action can require a second click with explicit confirmation copy; this is a presentation safeguard, not a replacement for server-side approval.
+
+The Block resource is self-contained, has no network/frame allowlist, constructs dynamic content with DOM text APIs, and accepts neither raw HTML nor an arbitrary URL/tool name. It stores only current form values in private widget state.
+
+## Page
+
+`render_mso_page` accepts an MSO-style route plus optional project/SHA context:
+
+- `/` — Page landing;
+- `/monitor` — native bounded VPS status;
+- `/project` — native project snapshot;
+- `/diff` — native project diff summary;
+- `/browser` — remote-browser handoff;
+- `/apps/<reviewed-app-id>` — reviewed app target.
+
+The model cannot pass raw HTML or an external URL. App identity, origin, start path, renderer, environment (`development`, `preview`, `production`, or `other`), sandbox, and presentation mode come from the code-owned `SURFACE_APPS` registry. An iframe target is valid only when its exact HTTPS origin is also present in the Page resource's `_meta.ui.csp.frameDomains`, and the browser runtime revalidates origin plus the approved path prefix before assigning `iframe.src`.
+
+Fresh 3 currently exposes one reviewed Page app: Play Together at `https://game.rahmanef.com/embed`, classified as `production`. The normal Play Together shell remains anti-frame; only `/embed` and `/embed/*` permit `https://mso-ui.rahmanef.com` as an ancestor. The Page sandbox omits popup and top-navigation privileges, authentication is not bypassed, and other MSO server scopes are not copied into this catalog.
-## Data boundaries
+Apps that keep restrictive `X-Frame-Options` or `frame-ancestors` remain `remote`. MSO preserves those protections and offers the Camoufox seam instead of stripping headers. User-installed runtime HTML apps and arbitrary HTML snippets cannot add themselves to the ChatGPT frame allowlist; they remain opaque-origin `srcDoc` content inside the authenticated MSO shell.
-The workflow component receives only workflow id, intent, resolved project label, timing, step count, and recent tool name/outcome/timestamp/duration. `workflow_status` is `ui.visibility:["app"]`, so polling is not another model action and is deliberately excluded from workflow-memory persistence.
+## Compatibility during migration
-The universal Surface receives no raw project/VPS HTML. Its native views call `project_get`, `project_diff`, and `vps_status` through MCP Apps `tools/call`; those data tools keep complete structured outputs for model/tool chaining but no longer own templates. Project output remains bounded to safe identity/Git/package/Convex/integration/knowledge metadata, diff UI consumes only summary/file metadata rather than interpolating the unified diff, and VPS output reuses the masked infrastructure summary layer so raw credentials never enter the widget.
+The canonical `resources/list` response advertises only Block and Page. Two previous URIs remain readable, but are not listed, so already-cached ChatGPT descriptors do not fail immediately:
-Both resources are self-contained: no external JavaScript, CSS, images, or direct `fetch()` calls. The workflow card retains `Open in MSO`; the Surface provides native routing and the reviewed app-demo renderer. A root MSO landing carrying ChatGPT's `redirectUrl=https://chatgpt.com/c/...` is server-redirected to `/assistant/mcp` while preserving the callback query; MSO never follows that callback itself.
+- `ui://mso/workflow-progress-v3.html` resolves to the Block resource. The Block recognizes the old workflow structured result and presents a small compatibility summary rather than the historical live progress dashboard.
+- `ui://mso/surface-v5.html` resolves to the Page resource.
-The universal **MSO Surface** is intentionally stricter than the ordinary runtime-app/HTML widgets. `render_mso_surface` accepts only an MSO-style route plus optional project/SHA context — never raw HTML and never an arbitrary URL. Nested frames can come only from the code-owned `SURFACE_APPS` registry and are permitted only when the exact origin is also present in the resource's `ui.csp.frameDomains`. The current Fresh 3 catalog has one reviewed iframe renderer for Play Together, so `frameDomains` contains exactly `https://game.rahmanef.com`. The browser-side renderer validates the returned app id and URL origin against the catalog bundled into the signed resource before setting `iframe.src`; dynamic labels use DOM `textContent`, not HTML interpolation. The iframe sandbox omits popup/top-navigation privileges. Apps that send `X-Frame-Options` or restrictive `frame-ancestors` remain `remote` and MSO does not strip those protections.
+`render_mso_surface` remains app-only as a compatibility alias for a cached Page widget and has no resource binding of its own. `workflow_status` likewise remains app-only for cached workflow widgets and native operator use. New model calls use `render_mso_page`; new workflows do not create a widget.
-Fresh 3 is the VPSKU MSO connector. Its current app target is **Play Together** at `https://game.rahmanef.com`. App identities and trusted origins from other MSO server scopes must not be copied into this catalog or CSP.
+## MCP contract
-Play Together framing is opt-in through a dedicated app boundary: the normal site remains protected, while `/embed` and `/embed/*` allow only `https://mso-ui.rahmanef.com` as the non-self frame ancestor. MSO reciprocally allows only `https://game.rahmanef.com` in the Surface resource CSP and revalidates both origin **and** the `/embed` path prefix before assigning `iframe.src`. The Surface sandbox still omits popups/top-navigation. Authentication is not bypassed; an unauthenticated iframe sees Play Together's normal Auth flow.
+1. `resources/list` / `resources/read` expose the two canonical `ui://…` resources as `text/html;profile=mcp-app`.
+2. Only `render_mso_block` and `render_mso_page` advertise `_meta.ui.resourceUri` plus the OpenAI `outputTemplate` compatibility alias.
+3. Every ChatGPT transport action declares an `outputSchema`. Stable UI-critical tools use typed schemas; other actions use the bounded `{ result }` envelope. Generic MCP clients retain their existing text fallback where applicable.
+4. Sandboxed Pages use the standard `tools/call` bridge for native data refreshes. ChatGPT-only helpers such as display mode, private widget state, follow-up messages, and `openExternal` are feature-detected.
+5. The dedicated UI origin is `https://mso-ui.rahmanef.com`. Standard CSP fields live only in `_meta.ui.csp`; the legacy `openai/widgetCSP` object retains only `redirect_domains` for `Open in MSO`.
-Installed `runtime:"html"` apps and user-authored HTML widgets are **not** trusted inputs to the ChatGPT frame allowlist. They remain useful inside the authenticated MSO shell, but promoting one into `SURFACE_APPS` requires an explicit code review/release. This separation prevents a user-installed manifest or HTML snippet from escalating into a ChatGPT nested-frame CSP capability. Raw HTML snippets continue to run only in opaque-origin `srcDoc` sandboxes. The authenticated cockpit itself remains non-frameable; no change is made to its `frame-ancestors` or `X-Frame-Options` policy.
+Current ChatGPT transport profile: **66 tools** — 64 model-visible actions (35 read / 17 write / 12 exec) plus app-only `workflow_status` and `render_mso_surface`. The full transport catalog has 90 tools. Exactly two tools bind UI resources: `render_mso_block` and `render_mso_page`.
+
+## Source boundaries
+
+| Contract | MSO source |
+| --- | --- |
+| Block resource/runtime | `lib/mcp/ui-block.ts` |
+| Block tool/schema | `lib/mcp/tools-block.ts` |
+| Page resource/runtime | `lib/mcp/ui-surface.ts`, `lib/mcp/ui-surface-script.ts`, `lib/mcp/ui-surface-style.ts` |
+| Page security catalog/router | `lib/mcp/surface-catalog.ts`, `lib/mcp/tools-surface.ts` |
+| Resource registry and legacy aliases | `lib/mcp/ui-resources.ts` |
+| Workflow bootstrap/lifecycle | `lib/mcp/tools-workflow-start.ts`, `lib/mcp/tools-workflow-lifecycle.ts` |
+| Resource capability / RPC | `lib/mcp/dispatch.ts` |
+| MCP descriptor/profile contract | `lib/mcp/tool-contract.ts` |
+| Toolset signature | `lib/mcp/toolset.ts` |
+| Contract tests | `lib/mcp/ui-resources.test.ts`, `lib/mcp/tools-block.test.ts`, `lib/mcp/tools-surface.test.ts`, `lib/mcp/surface-catalog.test.ts` |
## Flow
```text
ChatGPT model
│
- ├─ workflow_start ──→ workflow card ──→ workflow_status (app-only)
- ├─ project_get / project_diff / vps_status ──→ structured data only
- └─ render_mso_surface ─→ MSO Surface
- ├─ /monitor ──tools/call──→ vps_status
- ├─ /project ──tools/call──→ project_get
- ├─ /diff ──tools/call──→ project_diff
- ├─ exact-origin iframe only after explicit trust review
- └─ remote-browser seam for anti-frame apps
-
-All data tools keep portable structured/text results for non-MCP-Apps clients.
+ ├─ workflow_start ──→ structured workflow id only (headless)
+ │
+ ├─ bounded data/action tools ──→ structured/text results
+ │
+ ├─ render_mso_block ──→ compact validation/action/CRUD block
+ │ └─ user click → follow-up message
+ │ └─ normal scoped/approved tool call
+ │
+ └─ render_mso_page ──→ full MSO Page
+ ├─ /monitor ──tools/call──→ vps_status
+ ├─ /project ──tools/call──→ project_get
+ ├─ /diff ──tools/call──→ project_diff
+ ├─ exact-origin iframe after explicit review
+ └─ remote-browser seam for anti-frame apps
```
-## Dedicated UI origin
-
-Both templates keep standard CSP exclusively in `_meta.ui.csp`. The legacy `_meta["openai/widgetCSP"]` compatibility object contains only `redirect_domains` for `Open in MSO`; it deliberately does not duplicate `connect_domains`, `resource_domains`, or `frame_domains`. This keeps the scanner-facing policy single-source while preserving ChatGPT's trusted `openExternal` redirect allowlist.
-
-Both templates declare `_meta.ui.domain = https://mso-ui.rahmanef.com` and the ChatGPT compatibility alias `_meta["openai/widgetDomain"]` with the same origin. The sibling hostname is intentional: the cockpit may scope its session cookie to `mso.rahmanef.com`, while `mso-ui.rahmanef.com` is outside that cookie domain. The dedicated origin therefore satisfies the plugin UI identity requirement without reusing the authenticated dashboard origin.
-
-The reproducible Traefik route is stored in `ops/traefik/mso-ui.yml` and forwards only to the same local MSO service through the existing HTTPS/Let's Encrypt ingress. Widget CSP still allows no network/static-resource domains and only permits `Open in MSO` to redirect to `https://mso.rahmanef.com`.
-
## Manual ChatGPT smoke journeys
-Do not manually click through every model action. Cover the public contract with a small set of journeys that compose multiple primitives:
-
| Journey | Suggested prompt/action | Pass condition |
| --- | --- | --- |
-| Workflow/UI bridge | Start a read-only workflow for `mso`, press `Refresh`, then `Open in MSO` | progress updates; MSO opens visibly at Alfa → MCP Activity (`/assistant/mcp`), including when ChatGPT still uses a cached root-targeting widget; the explicit `Open directly` fallback targets the same view |
-| MSO Surface | Ask to render `/`, `/monitor`, then `/apps/play-together` | home/native view renders inline; Play Together loads only from `https://game.rahmanef.com/embed`; `frameDomains` contains exactly `https://game.rahmanef.com`; fullscreen remains user-initiated |
-| VPS / monitor | Ask for current VPS data, then render `/monitor` | `vps_status` returns structured data without a template; Surface renders CPU/memory/disk/apps/browser/infra and refresh works |
-| Project/Git | Ask to inspect project `mso`, then render `/project` or `/diff` | data tools return the correct project/branch/changes without templates; Surface presents them without secrets |
-| Safe filesystem CRUD | Create/read/copy/move/delete a disposable file under `~/mso-smoke-tests/` | content/hash round-trip succeeds and cleanup leaves no test file |
-| Convex | Check database status/tools for a known Convex project such as CareerPack | provider is Convex, project boundary is preserved, no env credential tools appear |
-| Project agent | Run `project_agent_run` in `plan_mode=true` for a harmless project inspection | returns a bounded plan/message id without modifying the repo |
-| Operator integrations | Check `browser_status` + `infra_providers_list` | read-only state is returned without starting browser/app or exposing provider secrets |
-
-This seven-journey suite is the preferred human acceptance test after a Scan Tools refresh. Full automated contract/coverage/build gates remain mandatory before release.
-
-## Deployment / refresh
-
-After a UI/schema release:
-
-1. run `bun run verify` and a production build;
-2. deploy through the normal MSO release path;
-3. refresh/re-scan the ChatGPT development app so `initialize`, `tools/list`, and `resources/list` are read again;
-4. verify all 64 ChatGPT transport tools expose `outputSchema` (63 model actions + app-only `workflow_status`); verify only `workflow_start` and `render_mso_surface` expose `_meta.ui.resourceUri`, while `project_get`, `project_diff`, and `vps_status` do not;
-5. verify `resources/list` contains exactly the dedicated workflow card plus universal Surface and each `resources/read` returns `text/html;profile=mcp-app`;
-6. verify both UI resources report `ui.domain=https://mso-ui.rahmanef.com`; for the universal Surface verify `ui.csp.frameDomains` contains only reviewed iframe origins, native data refreshes use `tools/call`, and `workflow_status` polling does not enter learned workflow steps;
-7. verify `skills/list`, `skills/get`, and each declared `skill://` resource/digest before the final Scan Tools refresh.
-
-If ChatGPT still renders text only after a verified deployment, treat a stale app/action snapshot as the first suspect before changing the server again.
+| Headless workflow | Start a harmless multi-step workflow | `workflow_start` returns a workflow id but opens no MCP App |
+| Validation Block | Render deployment checks with Approve/Revise actions | compact Block renders; click creates a follow-up; no mutation happens inside the widget |
+| CRUD Block | Render editable sample fields and a Save action | values remain editable, required validation works, and submitted values return through the follow-up message |
+| Native Page | Render `/monitor`, then `/project` | Page opens and refreshes bounded data through `tools/call` |
+| Production Page | Render `/apps/play-together` | iframe starts only at `https://game.rahmanef.com/embed`; fullscreen stays user-initiated |
+| Anti-frame fallback | Open a Page target classified `remote` | no header stripping or unreviewed frame occurs; the remote-browser handoff is shown |
+| Filesystem CRUD | Create/read/copy/move/delete a disposable file through ordinary tools | Block/Page presentation never changes the filesystem permission boundary |
+
+## Deployment and client refresh
+
+After changing UI resources or tool metadata:
+
+1. run targeted tests, `bun run verify`, and the official production release path;
+2. verify `initialize` reports MCP server `1.10.0` and toolset `2026.09.04.6`;
+3. verify `tools/list` exposes 66 ChatGPT transport tools, keeps `workflow_start` headless, marks the two compatibility actions app-only, and binds only `render_mso_block` / `render_mso_page`;
+4. verify `resources/list` contains exactly `ui://mso/block-v1.html` and `ui://mso/page-v1.html`, both with `text/html;profile=mcp-app`;
+5. verify Block has no frame domain and Page has only reviewed exact origins;
+6. refresh/re-scan the ChatGPT development app so its cached action/resource snapshot is replaced.
+
+A widget already rendered in an old conversation cannot be removed retroactively. After the server deployment, a stale workflow card indicates a cached ChatGPT connector snapshot, not a new `workflow_start` binding.
diff --git a/lib/mcp/parity.test.ts b/lib/mcp/parity.test.ts
index e9683aa1..c67d2563 100644
--- a/lib/mcp/parity.test.ts
+++ b/lib/mcp/parity.test.ts
@@ -99,8 +99,10 @@ const MCP_ONLY: Record<string, string> = {
"project.agent.run": "project-agent execution wraps the durable MCP/terminal AgentSession subagent runtime; Alfa browser threads have a separate lifecycle and approval identity",
"project.agent.status": "status belongs to project-agent message ids owned by the external MCP principal/session; Alfa has no compatible project-agent task ledger",
"vps.status": "this is an aggregate MCP Apps operator card over existing bounded host/app/browser/infra primitives; Alfa already renders equivalent in-shell operational surfaces",
- "mso.surface.apps.list": "the reviewed ChatGPT Surface demo catalog is MCP-App presentation metadata; Alfa already owns its in-shell app registry and must not inherit ChatGPT frame allowlists",
- "render.mso.surface": "the universal MSO Surface is a ChatGPT MCP Apps presentation target; Alfa already is an MSO presentation target and does not render another copy of itself",
+ "mso.surface.apps.list": "the reviewed ChatGPT Page app catalog is MCP-App presentation metadata; Alfa already owns its in-shell app registry and must not inherit ChatGPT frame allowlists",
+ "render.mso.block": "the compact Block is a ChatGPT MCP Apps presentation target for validation/action/CRUD handoff; Alfa already has native forms and approval cards",
+ "render.mso.page": "the full Page is a ChatGPT MCP Apps presentation target; Alfa already is an MSO presentation target and does not render another copy of itself",
+ "render.mso.surface": "app-only compatibility alias for cached pre-Page widgets; Alfa has no reason to expose the retired presentation name",
};
describe("Alfa ↔ MCP capability parity", () => {
diff --git a/lib/mcp/surface-catalog.test.ts b/lib/mcp/surface-catalog.test.ts
index 1159a90a..8f700f47 100644
--- a/lib/mcp/surface-catalog.test.ts
+++ b/lib/mcp/surface-catalog.test.ts
@@ -3,8 +3,8 @@ import { publicSurfaceApps, resolveSurfaceRoute, surfaceFrameDomains } from "./s
import { MSO_SURFACE_SCRIPT } from "./ui-surface-script";
import { OPEN_IN_MSO_SCRIPT } from "./ui-navigation";
-describe("MSO Surface trusted app catalog", () => {
- it("allowlists only the reviewed Play Together origin", () => {
+describe("MSO Page trusted app catalog", () => {
+ it("allowlists only the reviewed Play Together production origin", () => {
expect(surfaceFrameDomains()).toEqual(["https://game.rahmanef.com"]);
const apps = publicSurfaceApps();
expect(apps).toHaveLength(1);
@@ -14,6 +14,7 @@ describe("MSO Surface trusted app catalog", () => {
origin: "https://game.rahmanef.com",
startPath: "/embed",
renderer: "iframe",
+ environment: "production",
});
expect(JSON.stringify(apps)).not.toContain("sandbox");
});
@@ -34,7 +35,7 @@ describe("MSO Surface trusted app catalog", () => {
it("keeps every Play Together demo route inside /embed", () => {
const root = resolveSurfaceRoute("/apps/play-together");
expect(root).toMatchObject({ kind: "app", title: "Play Together", openPath: "/assistant/mcp" });
- expect(root.app).toMatchObject({ id: "play-together", renderer: "iframe" });
+ expect(root.app).toMatchObject({ id: "play-together", renderer: "iframe", environment: "production" });
expect(new URL(root.app!.url).pathname).toBe("/embed");
const room = resolveSurfaceRoute("/apps/play-together/room/ABCD?join=remote");
@@ -50,6 +51,7 @@ describe("MSO Surface trusted app catalog", () => {
expect(MSO_SURFACE_SCRIPT).not.toContain("insertAdjacentHTML");
expect(MSO_SURFACE_SCRIPT).not.toContain("document.write");
expect(MSO_SURFACE_SCRIPT).toContain('method:"tools/call"');
+ expect(MSO_SURFACE_SCRIPT).toContain('rpcCall("render_mso_page"');
expect(MSO_SURFACE_SCRIPT).not.toContain("window.openai.callTool");
expect(MSO_SURFACE_SCRIPT).toContain("url.origin!==safe.origin");
expect(MSO_SURFACE_SCRIPT).toContain("!url.pathname.startsWith(start+\"/\")");
diff --git a/lib/mcp/surface-catalog.ts b/lib/mcp/surface-catalog.ts
index 7ca7b997..d6bedef0 100644
--- a/lib/mcp/surface-catalog.ts
+++ b/lib/mcp/surface-catalog.ts
@@ -1,5 +1,6 @@
export type SurfaceRenderer = "iframe" | "remote";
export type SurfacePresentation = "inline" | "fullscreen" | "pip";
+export type SurfaceEnvironment = "development" | "preview" | "production" | "other";
export type SurfaceApp = {
id: string;
@@ -9,6 +10,7 @@ export type SurfaceApp = {
startPath: string;
renderer: SurfaceRenderer;
presentation: SurfacePresentation;
+ environment: SurfaceEnvironment;
sandbox?: string;
reason?: string;
};
@@ -26,6 +28,7 @@ export const SURFACE_APPS: readonly SurfaceApp[] = [
startPath: "/embed",
renderer: "iframe",
presentation: "fullscreen",
+ environment: "production",
sandbox: "allow-scripts allow-same-origin allow-forms allow-pointer-lock",
},
] as const;
@@ -89,7 +92,7 @@ export function resolveSurfaceRoute(rawRoute: string, context?: { project?: stri
if (parts[0] === "apps" && parts[1]) {
const app = surfaceAppById(parts[1]);
- if (!app) throw new Error(`unknown MSO Surface app: ${parts[1]}`);
+ if (!app) throw new Error(`unknown MSO Page app: ${parts[1]}`);
const suffix = parts.slice(2).join("/");
return {
route,
@@ -99,5 +102,5 @@ export function resolveSurfaceRoute(rawRoute: string, context?: { project?: stri
app: { ...app, url: safeDemoUrl(app, suffix, url.search) },
};
}
- throw new Error(`unsupported MSO Surface route: ${url.pathname}`);
+ throw new Error(`unsupported MSO Page route: ${url.pathname}`);
}
diff --git a/lib/mcp/tool-contract.ts b/lib/mcp/tool-contract.ts
index 1dc90fc8..f57f712b 100644
--- a/lib/mcp/tool-contract.ts
+++ b/lib/mcp/tool-contract.ts
@@ -35,7 +35,7 @@ export function outputSchemaForProfile(tool: McpTool, profile: McpToolProfile =
// names are discovered/called dynamically through project_mcp_* and NEVER appended
// to this list or TOOLS.
export const CHATGPT_TOOL_NAMES = new Set([
- // Workflow/session intelligence. workflow_status stays app-only at presentation time.
+ // Workflow/session intelligence. workflow_status and render_mso_surface stay app-only at presentation time.
"workflow_start", "workflow_status", "workflow_finish", "workflow_cancel",
"skills_search", "skills_list", "skills_read", "read_pipeline",
"agent_session_current", "agent_session_rename",
@@ -48,7 +48,7 @@ export const CHATGPT_TOOL_NAMES = new Set([
"project_database_status", "project_database_tools", "project_database_call", "project_database_query",
// Original MSO bounded VPS/file/application/browser power restored to ChatGPT.
- "vps_status", "mso_surface_apps_list", "render_mso_surface", "screen_capture", "fs_list", "fs_read", "fs_search", "fs_usage",
+ "vps_status", "mso_surface_apps_list", "render_mso_block", "render_mso_page", "render_mso_surface", "screen_capture", "fs_list", "fs_read", "fs_search", "fs_usage",
"fs_write", "fs_upload_file", "fs_mkdir", "fs_move", "fs_copy", "fs_delete",
"sys_stats", "sys_processes", "apps_list", "apps_logs", "apps_power", "browser_status", "browser_power",
@@ -62,6 +62,7 @@ export const CHATGPT_TOOL_NAMES = new Set([
const TITLES: Record<string, string> = {
workflow_start: "Start Workflow", workflow_status: "Workflow Status", workflow_finish: "Finish Workflow", workflow_cancel: "Cancel Workflow",
+ render_mso_block: "Render MSO Block", render_mso_page: "Render MSO Page", render_mso_surface: "Render MSO Surface (Compatibility)",
skills_search: "Search Skills", projects_list: "List Projects", project_capabilities: "Project Capabilities",
project_mcp_tools: "List Project MCP Tools", project_mcp_call: "Call Project MCP Tool", project_function_call: "Call Project Function",
read_pipeline: "Run Read Pipeline", fs_list: "List Files", fs_read: "Read File", fs_search: "Search Directories", fs_write: "Write File",
diff --git a/lib/mcp/tools-block.test.ts b/lib/mcp/tools-block.test.ts
new file mode 100644
index 00000000..bcdb972a
--- /dev/null
+++ b/lib/mcp/tools-block.test.ts
@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import { BLOCK_TOOLS } from "./tools-block";
+import { MSO_BLOCK_URI } from "./ui-block";
+
+const tool = BLOCK_TOOLS.find((row) => row.name === "render_mso_block");
+if (!tool) throw new Error("missing render_mso_block");
+
+describe("MSO Block MCP tool", () => {
+ it("normalizes bounded validation and CRUD input-output", async () => {
+ const result = await tool.run({
+ kind: "crud",
+ title: "Edit deployment",
+ description: "Review values before updating production.",
+ status: "warning",
+ fields: [
+ { id: "domain", label: "Domain", value: "example.com", input: "url", required: true },
+ { id: "enabled", label: "Enabled", value: true, input: "boolean" },
+ ],
+ checks: [{ label: "DNS", state: "pass", detail: "Resolved" }],
+ outputs: [{ label: "Environment", value: "production" }],
+ actions: [{ id: "save", label: "Save", style: "primary", prompt: "Apply the reviewed deployment update." }],
+ }, { scope: "read" }) as Record<string, unknown>;
+
+ expect(result).toMatchObject({
+ kind: "crud",
+ title: "Edit deployment",
+ status: "warning",
+ fields: [
+ { id: "domain", label: "Domain", value: "example.com", input: "url", editable: true, required: true },
+ { id: "enabled", label: "Enabled", value: true, input: "boolean", editable: true, required: false },
+ ],
+ checks: [{ label: "DNS", state: "pass", detail: "Resolved" }],
+ outputs: [{ label: "Environment", value: "production" }],
+ actions: [{ id: "save", label: "Save", style: "primary", prompt: "Apply the reviewed deployment update." }],
+ });
+ });
+
+ it("exposes only the Block resource and never accepts raw HTML or executable tool names", () => {
+ expect(tool.inputSchema.properties).not.toHaveProperty("html");
+ expect(tool.inputSchema.properties).not.toHaveProperty("url");
+ expect(tool.inputSchema.properties).not.toHaveProperty("tool");
+ expect(tool.meta).toMatchObject({
+ ui: { resourceUri: MSO_BLOCK_URI, visibility: ["model", "app"] },
+ "openai/outputTemplate": MSO_BLOCK_URI,
+ });
+ expect(JSON.stringify(tool.inputSchema)).toContain("Follow-up instruction");
+ });
+
+ it("bounds arrays and text while preserving explicit destructive confirmation copy", async () => {
+ const result = await tool.run({
+ kind: "action",
+ title: "Delete rows",
+ fields: Array.from({ length: 30 }, (_, index) => ({ id: `row-${index}`, label: `Row ${index}`, value: index })),
+ checks: Array.from({ length: 30 }, (_, index) => ({ label: `Check ${index}`, state: "info" })),
+ outputs: Array.from({ length: 30 }, (_, index) => ({ label: `Output ${index}`, value: index })),
+ actions: Array.from({ length: 12 }, (_, index) => ({
+ id: `action-${index}`,
+ label: `Action ${index}`,
+ style: index === 0 ? "danger" : "secondary",
+ prompt: "x".repeat(2_000),
+ confirm: index === 0 ? "Delete the selected rows?" : undefined,
+ })),
+ }, { scope: "read" }) as {
+ fields: unknown[]; checks: unknown[]; outputs: unknown[];
+ actions: Array<{ prompt: string; confirm?: string }>;
+ };
+
+ expect(result.fields).toHaveLength(20);
+ expect(result.checks).toHaveLength(20);
+ expect(result.outputs).toHaveLength(20);
+ expect(result.actions).toHaveLength(8);
+ expect(result.actions[0].prompt).toHaveLength(1_200);
+ expect(result.actions[0].confirm).toBe("Delete the selected rows?");
+ });
+});
diff --git a/lib/mcp/tools-block.ts b/lib/mcp/tools-block.ts
new file mode 100644
index 00000000..544272c7
--- /dev/null
+++ b/lib/mcp/tools-block.ts
@@ -0,0 +1,170 @@
+import { MSO_BLOCK_URI } from "./ui-block";
+import { type McpTool, READ_ONLY, S, str } from "./tool-kit";
+
+const SCALAR_SCHEMA = {
+ anyOf: [{ type: "string" }, { type: "number" }, { type: "boolean" }, { type: "null" }],
+} as const;
+
+const FIELD_SCHEMA = {
+ type: "object",
+ properties: {
+ id: { type: "string", minLength: 1, maxLength: 80 },
+ label: { type: "string", minLength: 1, maxLength: 160 },
+ value: SCALAR_SCHEMA,
+ input: { type: "string", enum: ["text", "number", "email", "url", "textarea", "boolean"] },
+ editable: { type: "boolean" },
+ required: { type: "boolean" },
+ placeholder: { type: "string", maxLength: 240 },
+ },
+ required: ["id", "label"],
+ additionalProperties: false,
+} as const;
+
+const CHECK_SCHEMA = {
+ type: "object",
+ properties: {
+ label: { type: "string", minLength: 1, maxLength: 200 },
+ state: { type: "string", enum: ["pass", "warn", "fail", "info"] },
+ detail: { type: "string", maxLength: 500 },
+ },
+ required: ["label", "state"],
+ additionalProperties: false,
+} as const;
+
+const OUTPUT_SCHEMA = {
+ type: "object",
+ properties: {
+ label: { type: "string", minLength: 1, maxLength: 160 },
+ value: SCALAR_SCHEMA,
+ },
+ required: ["label", "value"],
+ additionalProperties: false,
+} as const;
+
+const ACTION_SCHEMA = {
+ type: "object",
+ properties: {
+ id: { type: "string", minLength: 1, maxLength: 80 },
+ label: { type: "string", minLength: 1, maxLength: 120 },
+ style: { type: "string", enum: ["primary", "secondary", "danger"] },
+ prompt: {
+ type: "string",
+ minLength: 1,
+ maxLength: 1200,
+ description: "Follow-up instruction sent only after the user presses this button. Normal tool scope, approval, and audit rules still apply.",
+ },
+ confirm: { type: "string", maxLength: 240 },
+ },
+ required: ["id", "label", "prompt"],
+ additionalProperties: false,
+} as const;
+
+export const BLOCK_OUTPUT_SCHEMA = {
+ type: "object",
+ properties: {
+ kind: { type: "string", enum: ["validation", "crud", "action"] },
+ title: { type: "string" },
+ description: { type: "string" },
+ status: { type: "string", enum: ["neutral", "pending", "success", "warning", "error"] },
+ fields: { type: "array", items: FIELD_SCHEMA },
+ checks: { type: "array", items: CHECK_SCHEMA },
+ outputs: { type: "array", items: OUTPUT_SCHEMA },
+ actions: { type: "array", items: ACTION_SCHEMA },
+ },
+ required: ["kind", "title", "status", "fields", "checks", "outputs", "actions"],
+ additionalProperties: false,
+} as const;
+
+const text = (value: unknown, max: number, fallback = "") => {
+ if (typeof value !== "string") return fallback;
+ const clean = value.trim();
+ return clean ? clean.slice(0, max) : fallback;
+};
+
+const scalar = (value: unknown): string | number | boolean | null => {
+ if (typeof value === "string") return value.slice(0, 2_000);
+ if (typeof value === "number" && Number.isFinite(value)) return value;
+ if (typeof value === "boolean" || value === null) return value;
+ return "";
+};
+
+const choice = <T extends string>(value: unknown, allowed: readonly T[], fallback: T): T =>
+ typeof value === "string" && allowed.includes(value as T) ? value as T : fallback;
+
+function rows(value: unknown, max: number): Array<Record<string, unknown>> {
+ return Array.isArray(value)
+ ? value.filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object" && !Array.isArray(item)).slice(0, max)
+ : [];
+}
+
+function normalizeBlock(input: Record<string, unknown>) {
+ const fields = rows(input.fields, 20).map((field, index) => ({
+ id: text(field.id, 80, `field-${index + 1}`),
+ label: text(field.label, 160, `Field ${index + 1}`),
+ value: scalar(field.value),
+ input: choice(field.input, ["text", "number", "email", "url", "textarea", "boolean"] as const, "text"),
+ editable: field.editable !== false,
+ required: field.required === true,
+ ...(text(field.placeholder, 240) ? { placeholder: text(field.placeholder, 240) } : {}),
+ }));
+ const checks = rows(input.checks, 20).map((check) => ({
+ label: text(check.label, 200, "Check"),
+ state: choice(check.state, ["pass", "warn", "fail", "info"] as const, "info"),
+ ...(text(check.detail, 500) ? { detail: text(check.detail, 500) } : {}),
+ }));
+ const outputs = rows(input.outputs, 20).map((output) => ({
+ label: text(output.label, 160, "Result"),
+ value: scalar(output.value),
+ }));
+ const actions = rows(input.actions, 8).map((action, index) => ({
+ id: text(action.id, 80, `action-${index + 1}`),
+ label: text(action.label, 120, "Continue"),
+ style: choice(action.style, ["primary", "secondary", "danger"] as const, "secondary"),
+ prompt: text(action.prompt, 1_200, "Continue with the selected MSO action."),
+ ...(text(action.confirm, 240) ? { confirm: text(action.confirm, 240) } : {}),
+ }));
+
+ return {
+ kind: choice(input.kind, ["validation", "crud", "action"] as const, "action"),
+ title: text(input.title, 240, "MSO block"),
+ ...(text(input.description, 1_000) ? { description: text(input.description, 1_000) } : {}),
+ status: choice(input.status, ["neutral", "pending", "success", "warning", "error"] as const, "neutral"),
+ fields,
+ checks,
+ outputs,
+ actions,
+ };
+}
+
+export const BLOCK_TOOLS: McpTool[] = [
+ {
+ name: "render_mso_block",
+ title: "Render MSO Block",
+ description:
+ "Render a compact MCP App block only when a visible interaction helps: validation state, action buttons, or CRUD input-output. " +
+ "workflow_start is headless and never opens this automatically. Buttons send a user-approved follow-up to ChatGPT; the actual read/write/exec operation still uses the normal scoped tool, approval, and audit path. Raw HTML and arbitrary executable actions are not accepted.",
+ chatgptDescription:
+ "Render a compact validation/action/CRUD block. Use it only for user-facing confirmation or structured input-output; workflow_start stays invisible. Button presses return a follow-up to the chat and do not bypass tool approvals.",
+ scope: "read",
+ annotations: READ_ONLY,
+ inputSchema: S({
+ kind: { type: "string", enum: ["validation", "crud", "action"] },
+ title: { type: "string", minLength: 1, maxLength: 240 },
+ description: { type: "string", maxLength: 1_000 },
+ status: { type: "string", enum: ["neutral", "pending", "success", "warning", "error"] },
+ fields: { type: "array", maxItems: 20, items: FIELD_SCHEMA },
+ checks: { type: "array", maxItems: 20, items: CHECK_SCHEMA },
+ outputs: { type: "array", maxItems: 20, items: OUTPUT_SCHEMA },
+ actions: { type: "array", maxItems: 8, items: ACTION_SCHEMA },
+ }, ["kind", "title"]),
+ outputSchema: BLOCK_OUTPUT_SCHEMA,
+ meta: {
+ ui: { resourceUri: MSO_BLOCK_URI, visibility: ["model", "app"] },
+ "openai/outputTemplate": MSO_BLOCK_URI,
+ "openai/toolInvocation/invoking": "Preparing interaction…",
+ "openai/toolInvocation/invoked": "Interaction ready",
+ "openai/widgetAccessible": true,
+ },
+ run: async (input) => normalizeBlock({ ...input, title: str(input, "title") }),
+ },
+];
diff --git a/lib/mcp/tools-surface.test.ts b/lib/mcp/tools-surface.test.ts
index cc50d213..02048393 100644
--- a/lib/mcp/tools-surface.test.ts
+++ b/lib/mcp/tools-surface.test.ts
@@ -7,33 +7,54 @@ const tool = (name: string) => {
return value;
};
-describe("MSO Surface MCP tools", () => {
+describe("MSO Page MCP tools", () => {
it("returns only the server-reviewed public app catalog", async () => {
const result = await tool("mso_surface_apps_list").run({}, { scope: "read" }) as { apps: Array<Record<string, unknown>> };
expect(result.apps.map((app) => app.id)).toEqual(["play-together"]);
- expect(result.apps[0]).toMatchObject({ title: "Play Together", origin: "https://game.rahmanef.com", renderer: "iframe", startPath: "/embed" });
+ expect(result.apps[0]).toMatchObject({
+ title: "Play Together",
+ origin: "https://game.rahmanef.com",
+ renderer: "iframe",
+ startPath: "/embed",
+ environment: "production",
+ });
expect(JSON.stringify(result)).not.toContain("sandbox");
expect(JSON.stringify(result)).not.toContain("<script");
});
it("renders the VPSKU Play Together target without accepting a URL argument", async () => {
- const render = tool("render_mso_surface");
+ const render = tool("render_mso_page");
expect(render.inputSchema.properties).not.toHaveProperty("url");
expect(render.inputSchema.properties).not.toHaveProperty("html");
const result = await render.run({ route: "/apps/play-together" }, { scope: "read" }) as { app?: Record<string, unknown> };
- expect(result.app).toMatchObject({ id: "play-together", renderer: "iframe", origin: "https://game.rahmanef.com", startPath: "/embed", url: "https://game.rahmanef.com/embed" });
+ expect(result.app).toMatchObject({
+ id: "play-together",
+ renderer: "iframe",
+ origin: "https://game.rahmanef.com",
+ startPath: "/embed",
+ environment: "production",
+ url: "https://game.rahmanef.com/embed",
+ });
expect(result.app).not.toHaveProperty("sandbox");
});
- it("keeps scanner-facing Surface metadata scoped to Play Together", () => {
- const render = tool("render_mso_surface");
+ it("keeps scanner-facing Page metadata scoped to Play Together", () => {
+ const render = tool("render_mso_page");
const metadata = JSON.stringify({ description: render.description, chatgptDescription: render.chatgptDescription });
expect(metadata).toContain("play-together");
expect(metadata.toLowerCase()).not.toContain("antinrml");
});
it("keeps project identity separate from the route string", async () => {
- const result = await tool("render_mso_surface").run({ route: "/project", project: "mso" }, { scope: "read" });
+ const result = await tool("render_mso_page").run({ route: "/project", project: "mso" }, { scope: "read" });
expect(result).toMatchObject({ route: "/project", kind: "project", project: "mso", openPath: "/files" });
});
+
+ it("retains an app-only compatibility alias without another UI resource binding", async () => {
+ const legacy = tool("render_mso_surface");
+ expect(legacy.meta).toMatchObject({ ui: { visibility: ["app"] }, "openai/widgetAccessible": true });
+ expect((legacy.meta?.ui as { resourceUri?: string }).resourceUri).toBeUndefined();
+ const result = await legacy.run({ route: "/monitor" }, { scope: "read" });
+ expect(result).toMatchObject({ route: "/monitor", kind: "monitor", title: "System Monitor" });
+ });
});
diff --git a/lib/mcp/tools-surface.ts b/lib/mcp/tools-surface.ts
index d9cf17f6..588c42ca 100644
--- a/lib/mcp/tools-surface.ts
+++ b/lib/mcp/tools-surface.ts
@@ -1,5 +1,5 @@
import { type McpTool, S, str, opt, READ_ONLY } from "./tool-kit";
-import { MSO_SURFACE_URI } from "./ui-surface";
+import { MSO_PAGE_URI } from "./ui-surface";
import { publicSurfaceApps, resolveSurfaceRoute, type ResolvedSurface } from "./surface-catalog";
const APP_SCHEMA = {
@@ -7,13 +7,14 @@ const APP_SCHEMA = {
properties: {
id: { type: "string" }, title: { type: "string" }, description: { type: "string" }, origin: { type: "string" },
startPath: { type: "string" }, renderer: { type: "string", enum: ["iframe", "remote"] },
- presentation: { type: "string", enum: ["inline", "fullscreen", "pip"] }, reason: { type: "string" },
+ presentation: { type: "string", enum: ["inline", "fullscreen", "pip"] },
+ environment: { type: "string", enum: ["development", "preview", "production", "other"] }, reason: { type: "string" },
},
- required: ["id", "title", "description", "origin", "startPath", "renderer", "presentation"],
+ required: ["id", "title", "description", "origin", "startPath", "renderer", "presentation", "environment"],
additionalProperties: false,
} as const;
-const SURFACE_OUTPUT = {
+const PAGE_OUTPUT = {
type: "object",
properties: {
route: { type: "string" }, kind: { type: "string", enum: ["home", "monitor", "project", "diff", "browser", "app"] },
@@ -24,6 +25,12 @@ const SURFACE_OUTPUT = {
additionalProperties: false,
} as const;
+const PAGE_INPUT = S({
+ route: { type: "string", minLength: 1, maxLength: 1024, description: "MSO Page route. External URLs are rejected." },
+ project: { type: "string", description: "Project id/path/name for /project or /diff." },
+ sha: { type: "string", description: "Optional commit SHA for /diff." },
+}, ["route"]);
+
function publicResolved(resolved: ResolvedSurface): Record<string, unknown> {
const { app, ...rest } = resolved;
if (!app) return rest;
@@ -31,39 +38,51 @@ function publicResolved(resolved: ResolvedSurface): Record<string, unknown> {
return { ...rest, app: safeApp };
}
+const renderPage = async (input: Record<string, unknown>) => ({
+ ...publicResolved(resolveSurfaceRoute(str(input, "route"), { project: opt(input, "project"), sha: opt(input, "sha") })),
+ catalog: publicSurfaceApps(),
+});
+
export const SURFACE_TOOLS: McpTool[] = [
{
name: "mso_surface_apps_list",
- title: "List MSO Surface Apps",
- description: "List the small server-owned catalog of apps that MSO may present inside the ChatGPT MSO Surface. The model cannot add URLs or HTML to this catalog. Apps marked iframe have a reviewed exact frame origin; remote means the app keeps its own anti-framing policy and MSO will not strip it.",
- chatgptDescription: "List reviewed apps available to the ChatGPT MSO Surface, including whether each can be framed directly or must use the remote-browser seam.",
+ title: "List MSO Page Apps",
+ description: "List the small server-owned catalog of development or production apps that MSO may present inside the ChatGPT Page. The model cannot add URLs or HTML to this catalog. Apps marked iframe have a reviewed exact frame origin; remote means the app keeps its own anti-framing policy and MSO will not strip it.",
+ chatgptDescription: "List reviewed apps available to the ChatGPT MSO Page, including whether each can be framed directly or must use the remote-browser seam.",
scope: "read", annotations: READ_ONLY,
inputSchema: S({}),
outputSchema: { type: "object", properties: { apps: { type: "array", items: APP_SCHEMA } }, required: ["apps"], additionalProperties: false },
run: async () => ({ apps: publicSurfaceApps() }),
},
+ {
+ name: "render_mso_page",
+ title: "Render MSO Page",
+ description: "Render the full MSO Page MCP App for native operator views or reviewed development/production embeds. Use an MSO-style route such as /, /monitor, /project, /diff, /browser, or /apps/<reviewed-app-id>. For project/diff views pass project separately. This tool never accepts raw HTML or arbitrary external URLs; iframe targets come only from the server-owned allowlist.",
+ chatgptDescription: "Render the full secure MSO Page in ChatGPT. Native routes: /, /monitor, /project, /diff, /browser; reviewed live demo: /apps/play-together. Raw HTML and arbitrary URLs are rejected.",
+ scope: "read", annotations: READ_ONLY,
+ inputSchema: PAGE_INPUT,
+ outputSchema: PAGE_OUTPUT,
+ meta: {
+ ui: { resourceUri: MSO_PAGE_URI, visibility: ["model", "app"] },
+ "openai/outputTemplate": MSO_PAGE_URI,
+ "openai/toolInvocation/invoking": "Opening MSO Page…",
+ "openai/toolInvocation/invoked": "MSO Page opened",
+ "openai/widgetAccessible": true,
+ },
+ run: renderPage,
+ },
{
name: "render_mso_surface",
- title: "Render MSO Surface",
- description: "Render the universal MSO Surface MCP App. Use an MSO-style route such as /, /monitor, /project, /diff, /browser, or /apps/<reviewed-app-id>. For project/diff views pass project separately. This tool never accepts raw HTML or arbitrary external URLs; demo origins are resolved only from the server-owned allowlist.",
- chatgptDescription: "Render the secure interactive MSO Surface in ChatGPT. Native routes: /, /monitor, /project, /diff, /browser; reviewed live demo: /apps/play-together. Raw HTML and arbitrary URLs are rejected.",
+ title: "Render MSO Surface (Compatibility)",
+ description: "Compatibility alias for older MSO Page widgets. New model calls must use render_mso_page.",
+ chatgptDescription: "Compatibility-only app bridge for a cached MSO Surface. Use render_mso_page for new user-visible pages.",
scope: "read", annotations: READ_ONLY,
- inputSchema: S({
- route: { type: "string", minLength: 1, maxLength: 1024, description: "MSO Surface route. External URLs are rejected." },
- project: { type: "string", description: "Project id/path/name for /project or /diff." },
- sha: { type: "string", description: "Optional commit SHA for /diff." },
- }, ["route"]),
- outputSchema: SURFACE_OUTPUT,
+ inputSchema: PAGE_INPUT,
+ outputSchema: PAGE_OUTPUT,
meta: {
- ui: { resourceUri: MSO_SURFACE_URI, visibility: ["model", "app"] },
- "openai/outputTemplate": MSO_SURFACE_URI,
- "openai/toolInvocation/invoking": "Opening MSO Surface…",
- "openai/toolInvocation/invoked": "MSO Surface opened",
+ ui: { visibility: ["app"] },
"openai/widgetAccessible": true,
},
- run: async (a) => ({
- ...publicResolved(resolveSurfaceRoute(str(a, "route"), { project: opt(a, "project"), sha: opt(a, "sha") })),
- catalog: publicSurfaceApps(),
- }),
+ run: renderPage,
},
];
diff --git a/lib/mcp/tools-ui.ts b/lib/mcp/tools-ui.ts
new file mode 100644
index 00000000..229f1fe4
--- /dev/null
+++ b/lib/mcp/tools-ui.ts
@@ -0,0 +1,2 @@
+export { BLOCK_TOOLS } from "./tools-block";
+export { SURFACE_TOOLS } from "./tools-surface";
diff --git a/lib/mcp/tools-workflow-lifecycle.ts b/lib/mcp/tools-workflow-lifecycle.ts
index f266d4bd..72f3956c 100644
--- a/lib/mcp/tools-workflow-lifecycle.ts
+++ b/lib/mcp/tools-workflow-lifecycle.ts
@@ -13,7 +13,7 @@ export const WORKFLOW_LIFECYCLE_TOOLS: McpTool[] = [
{
name: "workflow_status",
description:
- "Return a redacted live status snapshot for one workflow. This tool exists for the MSO ChatGPT progress widget: it exposes only workflow identity, timing and high-level tool outcomes, never tool arguments, command strings, file contents or credentials.",
+ "Return a redacted live status snapshot for one workflow. This remains app-only for compatibility with cached progress widgets and MSO operator views; workflow_start itself is headless. It exposes only workflow identity, timing and high-level tool outcomes, never tool arguments, command strings, file contents or credentials.",
scope: "read",
annotations: { readOnlyHint: true, idempotentHint: true },
outputSchema: WORKFLOW_PROGRESS_OUTPUT,
diff --git a/lib/mcp/tools-workflow-start.ts b/lib/mcp/tools-workflow-start.ts
index c1878fce..a65eb9b4 100644
--- a/lib/mcp/tools-workflow-start.ts
+++ b/lib/mcp/tools-workflow-start.ts
@@ -10,7 +10,6 @@ import type { WorkflowOrchestrationSnapshot } from "@/lib/orchestration/types";
import type { McpTool } from "./tool-kit";
import { opt, S, str } from "./tool-kit";
import { toolsetInfo } from "./toolset";
-import { WORKFLOW_PROGRESS_URI } from "./ui-resources";
import { optionalStringList, visibleTools, WORKFLOW_PROGRESS_OUTPUT, workflowProgress } from "./tools-learning-shared";
export const WORKFLOW_START_TOOL: McpTool =
@@ -19,7 +18,7 @@ export const WORKFLOW_START_TOOL: McpTool =
description:
"The ONE startup call for a multi-step task. It starts the workflow, searches trusted skills and prior recipes, " +
"resolves project aliases, reports the current toolset/version, and inspects repository context when available. " +
- "Do not call skills_search first for the same task; this already includes it. Multiple conversations may start isolated workflows on one token; correlate every later step with the returned workflow_id.",
+ "Do not call skills_search first for the same task; this already includes it. Multiple conversations may start isolated workflows on one token; correlate every later step with the returned workflow_id. This tool is orchestration-only and never opens a UI by itself.",
scope: "write",
annotations: { idempotentHint: false },
outputSchema: WORKFLOW_PROGRESS_OUTPUT,
@@ -27,12 +26,6 @@ export const WORKFLOW_START_TOOL: McpTool =
if (!result || typeof result !== "object") return undefined;
return workflowProgress((result as { workflow?: unknown }).workflow, true);
},
- meta: {
- ui: { resourceUri: WORKFLOW_PROGRESS_URI, visibility: ["model", "app"] },
- "openai/outputTemplate": WORKFLOW_PROGRESS_URI,
- "openai/toolInvocation/invoking": "Starting MSO workflow…",
- "openai/toolInvocation/invoked": "MSO workflow ready",
- },
limit: { key: "workflow.memory", max: 30, windowMs: 60_000 },
audit: { action: "workflow.start" as const, targetArg: "project" },
inputSchema: S({
diff --git a/lib/mcp/tools.ts b/lib/mcp/tools.ts
index 643c8ac4..0292f747 100644
--- a/lib/mcp/tools.ts
+++ b/lib/mcp/tools.ts
@@ -17,7 +17,7 @@ import { READ_PIPELINE_TOOLS } from "./tools-read-pipeline";
import { PROJECT_MCP_TOOLS } from "./tools-project-mcp";
import { PROJECT_EXPERIENCE_TOOLS } from "./tools-project-experience";
import { OPERATOR_DASHBOARD_TOOLS } from "./tools-operator-dashboard";
-import { SURFACE_TOOLS } from "./tools-surface";
+import { BLOCK_TOOLS, SURFACE_TOOLS } from "./tools-ui";
import { withWorkflowContext } from "./tool-context";
// The write and exec tiers. Each carries an `audit` descriptor — the dispatcher,
@@ -227,4 +227,4 @@ const MUTATE_TOOLS: McpTool[] = [
},
];
-export const TOOLS: McpTool[] = [...READ_TOOLS, ...DISCOVERY_TOOLS, ...LEARNING_TOOLS, ...AGENT_TOOLS, ...LOCAL_AGENT_TOOLS, ...SUBAGENT_TOOLS, ...A2A_TOOLS, ...FORGE_TOOLS, ...READ_PIPELINE_TOOLS, ...PROJECT_MCP_TOOLS, ...PROJECT_EXPERIENCE_TOOLS, ...OPERATOR_DASHBOARD_TOOLS, ...SURFACE_TOOLS, ...INFRA_TOOLS, ...MUTATE_TOOLS, ...POWER_TOOLS].map(withWorkflowContext); export const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
+export const TOOLS: McpTool[] = [...READ_TOOLS, ...DISCOVERY_TOOLS, ...LEARNING_TOOLS, ...AGENT_TOOLS, ...LOCAL_AGENT_TOOLS, ...SUBAGENT_TOOLS, ...A2A_TOOLS, ...FORGE_TOOLS, ...READ_PIPELINE_TOOLS, ...PROJECT_MCP_TOOLS, ...PROJECT_EXPERIENCE_TOOLS, ...OPERATOR_DASHBOARD_TOOLS, ...BLOCK_TOOLS, ...SURFACE_TOOLS, ...INFRA_TOOLS, ...MUTATE_TOOLS, ...POWER_TOOLS].map(withWorkflowContext); export const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
diff --git a/lib/mcp/toolset.ts b/lib/mcp/toolset.ts
index 11a574ef..c6bfeb5c 100644
--- a/lib/mcp/toolset.ts
+++ b/lib/mcp/toolset.ts
@@ -3,9 +3,9 @@ import type { Scope } from "./scope";
import type { McpTool } from "./tool-kit";
import { toolDescriptor, type McpToolProfile } from "./tool-contract";
-export const MCP_SERVER_VERSION = "1.9.4";
-export const MCP_TOOLSET_VERSION = "2026.09.04.5";
-export const MCP_TOOLSET_CHANGED_AT = "2026-09-04T01:36:00Z";
+export const MCP_SERVER_VERSION = "1.10.0";
+export const MCP_TOOLSET_VERSION = "2026.09.04.6";
+export const MCP_TOOLSET_CHANGED_AT = "2026-09-04T09:36:00Z";
export type McpToolsetInfo = {
serverVersion: string;
diff --git a/lib/mcp/ui-block.ts b/lib/mcp/ui-block.ts
new file mode 100644
index 00000000..e5bda13a
--- /dev/null
+++ b/lib/mcp/ui-block.ts
@@ -0,0 +1,56 @@
+import { widgetResourceMeta } from "./ui-config";
+
+export const MSO_BLOCK_URI = "ui://mso/block-v1.html";
+const MIME = "text/html;profile=mcp-app";
+
+const html = String.raw`<main class="mso-block" aria-live="polite">
+<style>
+:root{color-scheme:light dark;font-family:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;--line:color-mix(in srgb,CanvasText 14%,transparent);--muted:color-mix(in srgb,CanvasText 58%,transparent);--soft:color-mix(in srgb,CanvasText 5%,Canvas);--accent:#7c3aed;--success:#16a34a;--warning:#d97706;--danger:#dc2626}*{box-sizing:border-box}html,body{margin:0;min-width:0;background:transparent;color:CanvasText}body{padding:7px}.card{overflow:hidden;border:1px solid var(--line);border-radius:16px;background:color-mix(in srgb,Canvas 97%,transparent);box-shadow:0 6px 24px color-mix(in srgb,#000 10%,transparent)}.head{display:flex;align-items:flex-start;gap:10px;padding:12px 12px 9px}.mark{display:grid;width:30px;height:30px;flex:0 0 30px;place-items:center;border-radius:9px;background:color-mix(in srgb,var(--accent) 17%,Canvas);font-size:12px;font-weight:850}.copy{min-width:0;flex:1}.eyebrow{font-size:8px;font-weight:750;letter-spacing:.09em;text-transform:uppercase;color:var(--muted)}h2{margin:2px 0 0;font-size:13px;line-height:1.3}.description{margin:4px 0 0;font-size:10px;line-height:1.45;color:var(--muted);overflow-wrap:anywhere}.status{flex:0 0 auto;border:1px solid var(--line);border-radius:999px;padding:4px 7px;font-size:8px;font-weight:800;letter-spacing:.06em;text-transform:uppercase}.status.pending{background:color-mix(in srgb,var(--accent) 12%,Canvas)}.status.success{background:color-mix(in srgb,var(--success) 12%,Canvas)}.status.warning{background:color-mix(in srgb,var(--warning) 13%,Canvas)}.status.error{background:color-mix(in srgb,var(--danger) 12%,Canvas)}.section{border-top:1px solid var(--line);padding:9px 12px}.section-title{margin:0 0 7px;font-size:8px;font-weight:750;letter-spacing:.08em;text-transform:uppercase;color:var(--muted)}.checks,.outputs{display:grid;gap:5px}.check,.output{display:grid;grid-template-columns:auto minmax(0,1fr) auto;align-items:center;gap:7px;min-height:27px}.dot{width:7px;height:7px;border-radius:50%;background:color-mix(in srgb,CanvasText 30%,transparent)}.dot.pass{background:var(--success)}.dot.warn{background:var(--warning)}.dot.fail{background:var(--danger)}.check strong,.output strong{min-width:0;font-size:10px}.detail,.value{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:9px;color:var(--muted)}.fields{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}.field{min-width:0}.field.full{grid-column:1/-1}.field label{display:block;margin-bottom:4px;font-size:9px;font-weight:650}.required{color:var(--danger)}input,textarea{width:100%;min-height:34px;border:1px solid var(--line);border-radius:9px;background:var(--soft);color:CanvasText;padding:7px 8px;font:inherit;font-size:10px;outline:none}textarea{min-height:72px;resize:vertical}input:focus,textarea:focus{border-color:color-mix(in srgb,var(--accent) 55%,var(--line));box-shadow:0 0 0 2px color-mix(in srgb,var(--accent) 15%,transparent)}.boolean{display:flex;min-height:34px;align-items:center;gap:7px;border:1px solid var(--line);border-radius:9px;padding:7px 8px;background:var(--soft);font-size:10px}.boolean input{width:15px;min-height:15px;margin:0}.readonly{min-height:34px;border:1px solid var(--line);border-radius:9px;padding:8px;background:var(--soft);font-size:10px;overflow-wrap:anywhere}.actions{display:flex;align-items:center;justify-content:flex-end;gap:6px;flex-wrap:wrap}.feedback{min-width:0;flex:1;font-size:9px;color:var(--muted)}button{appearance:none;min-height:32px;border:1px solid var(--line);border-radius:9px;background:var(--soft);color:CanvasText;padding:6px 10px;font:inherit;font-size:10px;font-weight:700;cursor:pointer}button.primary{background:color-mix(in srgb,var(--accent) 17%,Canvas)}button.danger{background:color-mix(in srgb,var(--danger) 12%,Canvas)}button:disabled{cursor:default;opacity:.55}button:focus-visible{outline:2px solid Highlight;outline-offset:2px}.empty{padding:4px 0;font-size:10px;color:var(--muted)}@media(max-width:520px){body{padding:4px}.card{border-radius:13px}.head{padding:10px}.section{padding:8px 10px}.fields{grid-template-columns:1fr}.field.full{grid-column:auto}.actions{align-items:stretch}.feedback{width:100%;flex-basis:100%}button{flex:1}}
+</style>
+<section class="card" aria-label="MSO interaction block">
+ <header class="head">
+ <div class="mark" aria-hidden="true">M</div>
+ <div class="copy"><div class="eyebrow" id="kind">Action</div><h2 id="title">MSO block</h2><p class="description" id="description" hidden></p></div>
+ <span class="status neutral" id="status">Ready</span>
+ </header>
+ <section class="section" id="checks-section" hidden><h3 class="section-title">Validation</h3><div class="checks" id="checks"></div></section>
+ <form id="form">
+ <section class="section" id="fields-section" hidden><h3 class="section-title">Input</h3><div class="fields" id="fields"></div></section>
+ <section class="section" id="outputs-section" hidden><h3 class="section-title">Output</h3><div class="outputs" id="outputs"></div></section>
+ <footer class="section actions" id="actions-section" hidden><span class="feedback" id="feedback" role="status" aria-live="polite"></span><div class="actions" id="actions"></div></footer>
+ </form>
+</section>
+<script>(()=>{
+const $=id=>document.getElementById(id);const kindEl=$("kind"),titleEl=$("title"),descriptionEl=$("description"),statusEl=$("status"),form=$("form"),feedback=$("feedback");
+const checksSection=$("checks-section"),checksEl=$("checks"),fieldsSection=$("fields-section"),fieldsEl=$("fields"),outputsSection=$("outputs-section"),outputsEl=$("outputs"),actionsSection=$("actions-section"),actionsEl=$("actions");
+let current=null;let confirmId="";let confirmTimer=0;
+const text=(value,fallback="")=>typeof value==="string"&&value.trim()?value.trim():fallback;
+const scalar=value=>typeof value==="string"||typeof value==="number"||typeof value==="boolean"||value===null?value:"";
+const clear=node=>{while(node.firstChild)node.removeChild(node.firstChild)};
+const el=(tag,className,value)=>{const node=document.createElement(tag);if(className)node.className=className;if(value!==undefined)node.textContent=String(value);return node};
+function workflowFallback(raw){if(!raw||typeof raw!=="object"||typeof raw.workflowId!=="string")return raw;return{kind:"validation",title:raw.active===false?"MSO workflow closed":"MSO workflow started",description:text(raw.intent,"Workflow orchestration continues in the background."),status:raw.active===false?"success":"pending",fields:[],checks:[],outputs:[...(raw.project?[{label:"Project",value:raw.project}]:[]),{label:"Steps",value:Number(raw.stepCount)||0}],actions:[]}}
+function normalize(raw){raw=workflowFallback(raw);if(!raw||typeof raw!=="object")return null;return{kind:["validation","crud","action"].includes(raw.kind)?raw.kind:"action",title:text(raw.title,"MSO block"),description:text(raw.description,""),status:["neutral","pending","success","warning","error"].includes(raw.status)?raw.status:"neutral",fields:Array.isArray(raw.fields)?raw.fields.slice(0,20):[],checks:Array.isArray(raw.checks)?raw.checks.slice(0,20):[],outputs:Array.isArray(raw.outputs)?raw.outputs.slice(0,20):[],actions:Array.isArray(raw.actions)?raw.actions.slice(0,8):[]}}
+function fieldValues(){const values={};for(const node of fieldsEl.querySelectorAll("[data-field-id]")){const id=node.dataset.fieldId;if(!id)continue;if(node instanceof HTMLInputElement&&node.type==="checkbox"){values[id]=node.checked;continue}if(node instanceof HTMLInputElement||node instanceof HTMLTextAreaElement){const value=node.value.slice(0,node instanceof HTMLTextAreaElement?2000:1000);if(node instanceof HTMLInputElement&&node.type==="number"&&value!==""){const parsed=Number(value);values[id]=Number.isFinite(parsed)?parsed:value}else values[id]=value}}return values}
+function persist(){try{if(window.openai&&typeof window.openai.setWidgetState==="function")window.openai.setWidgetState({modelContent:"MSO block: "+(current?.title||"action"),privateContent:{values:fieldValues()},imageIds:[]})}catch(_){}}
+function renderChecks(rows){clear(checksEl);checksSection.hidden=!rows.length;for(const row of rows){if(!row||typeof row!=="object")continue;const state=["pass","warn","fail","info"].includes(row.state)?row.state:"info";const item=el("div","check");item.append(el("span","dot "+state),el("strong","",text(row.label,"Check")),el("span","detail",text(row.detail,state)));checksEl.append(item)}}
+function renderFields(rows){clear(fieldsEl);fieldsSection.hidden=!rows.length;rows.forEach((row,index)=>{if(!row||typeof row!=="object")return;const id=text(row.id,"field-"+index),controlId="mso-field-"+index,inputType=["text","number","email","url","textarea","boolean"].includes(row.input)?row.input:"text",editable=row.editable!==false;const wrap=el("div","field"+(inputType==="textarea"?" full":""));const label=el("label","",text(row.label,id));label.id=controlId+"-label";if(row.required===true)label.append(el("span","required"," *"));wrap.append(label);if(!editable){const value=el("div","readonly",String(scalar(row.value)));value.id=controlId;value.setAttribute("aria-labelledby",label.id);wrap.append(value);fieldsEl.append(wrap);return}let input;if(inputType==="textarea"){input=document.createElement("textarea");input.value=String(scalar(row.value)).slice(0,2000);input.maxLength=2000}else{input=document.createElement("input");input.type=inputType==="boolean"?"checkbox":inputType;if(inputType==="boolean")input.checked=Boolean(row.value);else input.value=String(scalar(row.value)).slice(0,1000);if(["text","email","url"].includes(inputType))input.maxLength=1000}input.id=controlId;label.htmlFor=controlId;input.name=id;input.dataset.fieldId=id;input.required=row.required===true;if(text(row.placeholder,""))input.placeholder=text(row.placeholder,"");input.addEventListener("input",persist);if(inputType==="boolean"){const booleanWrap=el("div","boolean");booleanWrap.append(input,el("span","",text(row.placeholder,"Enabled")));wrap.append(booleanWrap)}else wrap.append(input);fieldsEl.append(wrap)})}
+function renderOutputs(rows){clear(outputsEl);outputsSection.hidden=!rows.length;for(const row of rows){if(!row||typeof row!=="object")continue;const item=el("div","output");item.append(el("span","dot info"),el("strong","",text(row.label,"Result")),el("span","value",String(scalar(row.value))));outputsEl.append(item)}}
+async function submit(action){if(!action||typeof action!=="object")return;if(text(action.confirm,"")&&confirmId!==action.id){confirmId=text(action.id,"");feedback.textContent=text(action.confirm,"Press the action again to confirm.");window.clearTimeout(confirmTimer);confirmTimer=window.setTimeout(()=>{confirmId="";feedback.textContent=""},6000);return}confirmId="";window.clearTimeout(confirmTimer);if(!form.reportValidity())return;const payload={actionId:text(action.id,"action"),blockKind:current.kind,values:fieldValues()};const prompt=text(action.prompt,"Continue with the selected MSO action.")+"\n\nMSO block submission:\n"+JSON.stringify(payload,null,2).slice(0,12000);feedback.textContent="Sending to chat…";try{if(!window.openai||typeof window.openai.sendFollowUpMessage!=="function")throw new Error("unsupported");await window.openai.sendFollowUpMessage({prompt});feedback.textContent="Sent to chat."}catch(_){feedback.textContent="Interactive handoff is unavailable. Continue in the chat."}}
+function renderActions(rows){clear(actionsEl);actionsSection.hidden=!rows.length;for(const row of rows){if(!row||typeof row!=="object")continue;const button=el("button",["primary","secondary","danger"].includes(row.style)?row.style:"secondary",text(row.label,"Continue"));button.type="button";button.addEventListener("click",()=>submit(row));actionsEl.append(button)}}
+function render(raw){const next=normalize(raw);if(!next)return;current=next;kindEl.textContent=next.kind;titleEl.textContent=next.title;descriptionEl.textContent=next.description;descriptionEl.hidden=!next.description;statusEl.className="status "+next.status;statusEl.textContent=next.status==="neutral"?"Ready":next.status;renderChecks(next.checks);renderFields(next.fields);renderOutputs(next.outputs);renderActions(next.actions);persist()}
+function readHostOutput(){const output=window.openai&&window.openai.toolOutput;if(output)render(output)}
+window.addEventListener("message",event=>{if(event.source!==window.parent)return;const message=event.data;if(message&&message.method==="ui/notifications/tool-result"&&message.params&&message.params.structuredContent)render(message.params.structuredContent)},{passive:true});
+window.addEventListener("openai:set_globals",readHostOutput,{passive:true});readHostOutput();
+})();</script>
+</main>`;
+
+export const MSO_BLOCK_RESOURCE = {
+ uri: MSO_BLOCK_URI,
+ name: "MSO Block",
+ description: "Compact validation, action, and CRUD input-output component for ChatGPT.",
+ mimeType: MIME,
+ text: html,
+ _meta: widgetResourceMeta(
+ "Compact MSO interaction block. It renders bounded text fields, validation states, outputs, and user-approved action handoffs; it never executes a mutation by itself.",
+ ),
+} as const;
diff --git a/lib/mcp/ui-resources.test.ts b/lib/mcp/ui-resources.test.ts
index 59eed6fb..391c2839 100644
--- a/lib/mcp/ui-resources.test.ts
+++ b/lib/mcp/ui-resources.test.ts
@@ -3,15 +3,22 @@ import { describe, expect, it, vi } from "vitest";
vi.mock("server-only", () => ({}));
const { dispatch } = await import("./dispatch");
-const { MCP_APP_MIME_TYPE, WORKFLOW_PROGRESS_URI, MSO_SURFACE_URI, readUiResource } = await import("./ui-resources");
+const {
+ MCP_APP_MIME_TYPE,
+ MSO_BLOCK_URI,
+ MSO_PAGE_URI,
+ LEGACY_WORKFLOW_PROGRESS_URI,
+ LEGACY_SURFACE_URI,
+ readUiResource,
+} = await import("./ui-resources");
const { MCP_UI_DOMAIN, MSO_ORIGIN } = await import("./ui-config");
const { activeWorkflowForActor } = await import("@/lib/workflow");
const call = (name: string, args: Record<string, unknown> = {}) =>
({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } });
-describe("MCP Apps workflow progress UI", () => {
- it("advertises resources and binds workflow_start to the progress resource", async () => {
+describe("MCP Apps Block and Page contract", () => {
+ it("keeps workflow_start headless and binds only explicit Block/Page render tools", async () => {
const initialized = await dispatch({ id: 1, method: "initialize" }, "write", "mcp:ui-init");
expect(initialized.result).toMatchObject({
capabilities: { tools: { listChanged: false }, resources: { listChanged: false } },
@@ -21,12 +28,11 @@ describe("MCP Apps workflow progress UI", () => {
const tools = (listed.result as {
tools: Array<{ name: string; outputSchema?: unknown; _meta?: Record<string, unknown> }>;
}).tools;
+
const start = tools.find((tool) => tool.name === "workflow_start");
expect(start?.outputSchema).toBeDefined();
- expect(start?._meta).toMatchObject({
- ui: { resourceUri: WORKFLOW_PROGRESS_URI, visibility: ["model", "app"] },
- "openai/outputTemplate": WORKFLOW_PROGRESS_URI,
- });
+ expect((start?._meta?.ui as { resourceUri?: string } | undefined)?.resourceUri).toBeUndefined();
+ expect(start?._meta?.["openai/outputTemplate"]).toBeUndefined();
const status = tools.find((tool) => tool.name === "workflow_status");
expect(status?.outputSchema).toBeDefined();
@@ -35,61 +41,120 @@ describe("MCP Apps workflow progress UI", () => {
"openai/widgetAccessible": true,
});
+ const block = tools.find((tool) => tool.name === "render_mso_block");
+ expect(block?.outputSchema).toBeDefined();
+ expect(block?._meta).toMatchObject({
+ ui: { resourceUri: MSO_BLOCK_URI, visibility: ["model", "app"] },
+ "openai/outputTemplate": MSO_BLOCK_URI,
+ "openai/widgetAccessible": true,
+ });
+
+ const page = tools.find((tool) => tool.name === "render_mso_page");
+ expect(page?.outputSchema).toBeDefined();
+ expect(page?._meta).toMatchObject({
+ ui: { resourceUri: MSO_PAGE_URI, visibility: ["model", "app"] },
+ "openai/outputTemplate": MSO_PAGE_URI,
+ "openai/widgetAccessible": true,
+ });
+
+ const legacy = tools.find((tool) => tool.name === "render_mso_surface");
+ expect(legacy?._meta).toMatchObject({ ui: { visibility: ["app"] }, "openai/widgetAccessible": true });
+ expect((legacy?._meta?.ui as { resourceUri?: string } | undefined)?.resourceUri).toBeUndefined();
+ expect(legacy?._meta?.["openai/outputTemplate"]).toBeUndefined();
+
+ const resourceBound = tools
+ .filter((tool) => Boolean((tool._meta?.ui as { resourceUri?: string } | undefined)?.resourceUri))
+ .map((tool) => tool.name)
+ .sort();
+ expect(resourceBound).toEqual(["render_mso_block", "render_mso_page"]);
+ const appOnly = tools
+ .filter((tool) => {
+ const visibility = (tool._meta?.ui as { visibility?: string[] } | undefined)?.visibility;
+ return Array.isArray(visibility) && visibility.includes("app") && !visibility.includes("model");
+ })
+ .map((tool) => tool.name)
+ .sort();
+ expect(appOnly).toEqual(["render_mso_surface", "workflow_status"]);
+
for (const name of ["project_get", "project_diff", "vps_status"] as const) {
const tool = tools.find((row) => row.name === name);
expect(tool?.outputSchema, name).toBeDefined();
expect((tool?._meta?.ui as { resourceUri?: string } | undefined)?.resourceUri, name).toBeUndefined();
expect(tool?._meta?.["openai/outputTemplate"], name).toBeUndefined();
}
-
- const surface = tools.find((row) => row.name === "render_mso_surface");
- expect(surface?.outputSchema).toBeDefined();
- expect(surface?._meta).toMatchObject({
- ui: { resourceUri: MSO_SURFACE_URI, visibility: ["model", "app"] },
- "openai/outputTemplate": MSO_SURFACE_URI,
- "openai/widgetAccessible": true,
- });
});
- it("serves one self-contained mcp-app resource", async () => {
+ it("advertises exactly two canonical resources: one Block and one Page", async () => {
const listed = await dispatch({ id: 1, method: "resources/list" }, "read", "mcp:ui-resource");
- const resources = (listed.result as { resources: Array<{ uri: string; mimeType: string }> }).resources;
- expect(resources).toHaveLength(2);
- expect(resources).toEqual(expect.arrayContaining([
- expect.objectContaining({ uri: WORKFLOW_PROGRESS_URI, mimeType: MCP_APP_MIME_TYPE }),
- expect.objectContaining({ uri: MSO_SURFACE_URI, mimeType: MCP_APP_MIME_TYPE }),
- ]));
-
- const read = await dispatch({ id: 2, method: "resources/read", params: { uri: WORKFLOW_PROGRESS_URI } }, "read", "mcp:ui-resource");
+ const resources = (listed.result as { resources: Array<{ uri: string; name: string; mimeType: string }> }).resources;
+ expect(resources).toEqual([
+ expect.objectContaining({ uri: MSO_BLOCK_URI, name: "MSO Block", mimeType: MCP_APP_MIME_TYPE }),
+ expect.objectContaining({ uri: MSO_PAGE_URI, name: "MSO Page", mimeType: MCP_APP_MIME_TYPE }),
+ ]);
+ });
+
+ it("serves a self-contained compact Block with user-approved follow-up actions", async () => {
+ const read = await dispatch({ id: 2, method: "resources/read", params: { uri: MSO_BLOCK_URI } }, "read", "mcp:ui-block");
const content = (read.result as {
- contents: Array<{ uri: string; mimeType: string; text: string; _meta: Record<string, unknown> }>;
+ contents: Array<{ uri: string; mimeType: string; text: string; _meta: Record<string, any> }>;
}).contents[0];
- expect(content.uri).toBe(WORKFLOW_PROGRESS_URI);
+ expect(content.uri).toBe(MSO_BLOCK_URI);
expect(content.mimeType).toBe(MCP_APP_MIME_TYPE);
- expect(content.text).toContain("workflow_status");
- expect(content.text).toContain("Open in MSO");
- expect(content.text).toContain("openExternal");
- expect(content.text).toContain("setOpenInAppUrl");
- expect(content.text).toContain("Open directly");
- expect(content.text).toContain("/assistant/mcp");
- expect(content.text).toContain("Automatic open unavailable");
- expect(WORKFLOW_PROGRESS_URI).toContain("-v3.html");
+ expect(content.text).toContain("sendFollowUpMessage");
+ expect(content.text).toContain("reportValidity");
+ expect(content.text).toContain("label.id=controlId+\"-label\"");
+ expect(content.text).toContain("label.htmlFor=controlId");
+ expect(content.text).toContain("aria-labelledby");
+ expect(content.text).toContain("input.maxLength=2000");
+ expect(content.text).toContain("slice(0,12000)");
+ expect(content.text).toContain("MSO block submission");
+ expect(content.text).toContain("workflowFallback");
+ const script = content.text.match(/<script>([\s\S]*)<\/script>/)?.[1];
+ expect(script).toBeTruthy();
+ expect(() => new Function(script!)).not.toThrow();
expect(content.text).not.toContain("fetch(");
+ expect(content.text).not.toContain('method:"tools/call"');
+ expect(content.text).not.toContain("dangerouslySetInnerHTML");
expect(content._meta).toMatchObject({
- ui: { domain: MCP_UI_DOMAIN, prefersBorder: true },
+ ui: { domain: MCP_UI_DOMAIN, prefersBorder: true, csp: { connectDomains: [], resourceDomains: [] } },
"openai/widgetDomain": MCP_UI_DOMAIN,
"openai/widgetPrefersBorder": true,
});
+ expect(content._meta.ui.csp.frameDomains).toBeUndefined();
expect(content._meta["openai/widgetCSP"]).toEqual({ redirect_domains: [MSO_ORIGIN] });
+ expect(MSO_BLOCK_URI).toContain("block-v1.html");
});
- it("returns only redacted structured workflow state and keeps polling out of workflow memory", async () => {
+ it("serves the full Page with a minimal reviewed nested-frame allowlist", async () => {
+ const read = await dispatch({ id: 30, method: "resources/read", params: { uri: MSO_PAGE_URI } }, "read", "mcp:ui-page");
+ const content = (read.result as { contents: Array<{ mimeType: string; text: string; _meta: Record<string, any> }> }).contents[0];
+ expect(content.mimeType).toBe(MCP_APP_MIME_TYPE);
+ expect(content.text).toContain("requestDisplayMode");
+ expect(content.text).toContain("setWidgetState");
+ expect(content.text).toContain("render_mso_page");
+ expect(content.text).toContain("https://game.rahmanef.com");
+ expect(content.text).toContain('"environment":"production"');
+ expect(content.text).toContain('app.environment+" · "+app.renderer');
+ expect(content.text).not.toContain("fetch(");
+ expect(content.text).not.toContain("allow-popups");
+ expect(content.text).not.toContain("allow-top-navigation");
+ expect(content.text).not.toContain("dangerouslySetInnerHTML");
+ expect(content._meta.ui.csp).toMatchObject({
+ connectDomains: [],
+ resourceDomains: [],
+ frameDomains: ["https://game.rahmanef.com"],
+ });
+ expect(content._meta["openai/widgetCSP"]).toEqual({ redirect_domains: [MSO_ORIGIN] });
+ expect(MSO_PAGE_URI).toContain("page-v1.html");
+ });
+
+ it("returns only redacted structured workflow state and keeps status polling out of workflow memory", async () => {
const actor = `mcp:ui-status-${Date.now()}`;
const projectHint = "/private/operator/projects/mso";
const started = await dispatch(call("workflow_start", {
- intent: "verify the ChatGPT progress widget",
+ intent: "verify the headless workflow contract",
project: projectHint,
- constraints: "never expose secret-token=example in the widget",
+ constraints: "never expose secret-token=example in structured output",
}), "write", actor);
const startResult = started.result as {
structuredContent?: {
@@ -109,9 +174,6 @@ describe("MCP Apps workflow progress UI", () => {
expect(startResult.structuredContent).not.toHaveProperty("search");
expect(JSON.stringify(startResult.structuredContent)).not.toContain(projectHint);
expect(JSON.stringify(startResult.structuredContent)).not.toContain("secret-token");
-
- // The portable text fallback intentionally keeps the pre-existing result shape
- // for MCP clients that do not render Apps UI.
expect(JSON.parse(startResult.content[0].text).workflow.id).toBe(workflowId);
const before = await activeWorkflowForActor(actor, workflowId!);
@@ -133,8 +195,21 @@ describe("MCP Apps workflow progress UI", () => {
expect((closed.result as { structuredContent?: { active: boolean } }).structuredContent?.active).toBe(false);
});
+ it("keeps latest cached workflow/surface URIs as non-advertised Block/Page aliases", async () => {
+ const canonicalBlock = readUiResource(MSO_BLOCK_URI);
+ const canonicalPage = readUiResource(MSO_PAGE_URI);
+ const legacyBlock = readUiResource(LEGACY_WORKFLOW_PROGRESS_URI);
+ const legacyPage = readUiResource(LEGACY_SURFACE_URI);
+ expect(legacyBlock).toMatchObject({ uri: LEGACY_WORKFLOW_PROGRESS_URI, text: canonicalBlock?.text });
+ expect(legacyPage).toMatchObject({ uri: LEGACY_SURFACE_URI, text: canonicalPage?.text });
+
+ const listed = await dispatch({ id: 31, method: "resources/list" }, "read", "mcp:ui-alias");
+ const serialized = JSON.stringify(listed.result);
+ expect(serialized).not.toContain(LEGACY_WORKFLOW_PROGRESS_URI);
+ expect(serialized).not.toContain(LEGACY_SURFACE_URI);
+ });
- it("retires specialized operator resources in favor of the universal Surface", async () => {
+ it("retires specialized operator resources in favor of the Page", async () => {
for (const uri of [
"ui://mso/project-status-v2.html",
"ui://mso/project-diff-v2.html",
@@ -146,37 +221,13 @@ describe("MCP Apps workflow progress UI", () => {
}
});
- it("serves the universal MSO Surface with a minimal nested-frame allowlist", async () => {
- const read = await dispatch({ id: 30, method: "resources/read", params: { uri: MSO_SURFACE_URI } }, "read", "mcp:ui-surface");
- const content = (read.result as { contents: Array<{ mimeType: string; text: string; _meta: Record<string, any> }> }).contents[0];
- expect(content.mimeType).toBe(MCP_APP_MIME_TYPE);
- expect(content.text).toContain("requestDisplayMode");
- expect(content.text).toContain("setWidgetState");
- expect(content.text).toContain("render_mso_surface");
- expect(content.text).toContain("https://game.rahmanef.com");
- expect(content.text).not.toContain("fetch(");
- expect(content.text).not.toContain("allow-popups");
- expect(content.text).not.toContain("allow-top-navigation");
- expect(content.text).not.toContain("dangerouslySetInnerHTML");
- expect(content._meta.ui.csp).toMatchObject({
- connectDomains: [],
- resourceDomains: [],
- frameDomains: ["https://game.rahmanef.com"],
- });
- expect(content._meta["openai/widgetCSP"]).toEqual({
- redirect_domains: [MSO_ORIGIN],
- });
- expect(MSO_SURFACE_URI).toContain("surface-v5.html");
- });
-
- it("keeps one dedicated progress card and one universal general-purpose Surface", () => {
- expect(readUiResource(WORKFLOW_PROGRESS_URI)?.text).toContain('data-mso-path="/assistant/mcp"');
- const surface = readUiResource(MSO_SURFACE_URI)?.text ?? "";
- expect(surface).toContain('route:"/monitor"');
- expect(surface).toContain('route:"/project"');
- expect(surface).toContain('route:"/diff"');
- expect(surface).toContain('route:"/browser"');
- expect(surface).toContain('method:"tools/call"');
+ it("keeps native Page routes and portable tools/call refreshes", () => {
+ const page = readUiResource(MSO_PAGE_URI)?.text ?? "";
+ expect(page).toContain('route:"/monitor"');
+ expect(page).toContain('route:"/project"');
+ expect(page).toContain('route:"/diff"');
+ expect(page).toContain('route:"/browser"');
+ expect(page).toContain('method:"tools/call"');
});
it("rejects unknown UI resource URIs", async () => {
diff --git a/lib/mcp/ui-resources.ts b/lib/mcp/ui-resources.ts
index 858db79c..40730a9f 100644
--- a/lib/mcp/ui-resources.ts
+++ b/lib/mcp/ui-resources.ts
@@ -1,205 +1,14 @@
-import { MSO_SURFACE_RESOURCE } from "./ui-surface";
-import { widgetResourceMeta } from "./ui-config";
-import { OPEN_IN_MSO_SCRIPT, openInMsoControls } from "./ui-navigation";
-export { MSO_SURFACE_URI } from "./ui-surface";
-export const WORKFLOW_PROGRESS_URI = "ui://mso/workflow-progress-v3.html";
-export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
+import { MSO_BLOCK_RESOURCE, MSO_BLOCK_URI } from "./ui-block";
+import { MSO_PAGE_RESOURCE, MSO_PAGE_URI } from "./ui-surface";
-const workflowProgressHtml = String.raw`<main class="mso-workflow" aria-live="polite">
- <style>
- :root { color-scheme: light dark; font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
- * { box-sizing: border-box; }
- body { margin: 0; background: transparent; color: CanvasText; }
- .mso-workflow { min-width: 0; padding: 14px; }
- .card { border: 1px solid color-mix(in srgb, CanvasText 16%, transparent); border-radius: 18px; background: color-mix(in srgb, Canvas 94%, transparent); overflow: hidden; }
- .head { display: flex; gap: 12px; align-items: flex-start; padding: 14px 14px 10px; }
- .mark { width: 34px; height: 34px; flex: 0 0 34px; display: grid; place-items: center; border-radius: 10px; background: color-mix(in srgb, #7c3aed 18%, Canvas); font-weight: 800; }
- .title { min-width: 0; flex: 1; }
- h2 { margin: 0; font-size: 15px; line-height: 1.3; }
- .intent { margin: 4px 0 0; color: color-mix(in srgb, CanvasText 67%, transparent); font-size: 12px; line-height: 1.4; overflow-wrap: anywhere; }
- .status { flex: 0 0 auto; border-radius: 999px; padding: 4px 8px; font-size: 10px; font-weight: 750; letter-spacing: .07em; border: 1px solid color-mix(in srgb, CanvasText 16%, transparent); }
- .status.active { background: color-mix(in srgb, #22c55e 12%, Canvas); }
- .status.closed { background: color-mix(in srgb, CanvasText 7%, Canvas); }
- .meta { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 1px; background: color-mix(in srgb, CanvasText 10%, transparent); border-block: 1px solid color-mix(in srgb, CanvasText 10%, transparent); }
- .metric { min-width: 0; background: Canvas; padding: 9px 11px; }
- .metric span { display: block; color: color-mix(in srgb, CanvasText 55%, transparent); font-size: 9px; text-transform: uppercase; letter-spacing: .09em; }
- .metric strong { display: block; margin-top: 2px; font-size: 12px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
- .steps { padding: 10px 14px 8px; }
- .steps-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-bottom: 6px; }
- .steps-head strong { font-size: 11px; }
- .steps-head span { color: color-mix(in srgb, CanvasText 52%, transparent); font-size: 10px; }
- ol { list-style: none; margin: 0; padding: 0; }
- li { display: grid; grid-template-columns: 9px minmax(0, 1fr) auto; align-items: center; gap: 8px; min-height: 29px; border-top: 1px solid color-mix(in srgb, CanvasText 8%, transparent); font-size: 11px; }
- li:first-child { border-top: 0; }
- .dot { width: 7px; height: 7px; border-radius: 50%; background: color-mix(in srgb, CanvasText 35%, transparent); }
- .dot.completed { background: #22c55e; }
- .dot.failed, .dot.denied, .dot.rate_limited, .dot.invalid_args { background: #ef4444; }
- .tool { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
- .duration { color: color-mix(in srgb, CanvasText 50%, transparent); font-variant-numeric: tabular-nums; }
- .empty { padding: 8px 0 10px; color: color-mix(in srgb, CanvasText 52%, transparent); font-size: 11px; }
- .foot { display: flex; align-items: center; justify-content: space-between; gap: 8px; padding: 8px 10px 10px 14px; }
- .connection { color: color-mix(in srgb, CanvasText 52%, transparent); font-size: 10px; }
- .actions { display: flex; align-items: center; justify-content: flex-end; gap: 6px; flex-wrap: wrap; }
- .open-direct { color: CanvasText; font-size: 10px; text-decoration: none; border-bottom: 1px solid currentColor; }
- .open-feedback { width: 100%; text-align: right; color: color-mix(in srgb, CanvasText 52%, transparent); font-size: 9px; }
- button { appearance: none; border: 1px solid color-mix(in srgb, CanvasText 16%, transparent); background: color-mix(in srgb, CanvasText 6%, Canvas); color: CanvasText; border-radius: 10px; padding: 7px 10px; min-height: 32px; font: inherit; font-size: 11px; font-weight: 650; cursor: pointer; }
- button.primary { background: color-mix(in srgb, #7c3aed 17%, Canvas); }
- button:focus-visible { outline: 2px solid Highlight; outline-offset: 2px; }
- @media (max-width: 440px) { .mso-workflow { padding: 8px; } .head { padding: 11px 11px 8px; } .meta { grid-template-columns: 1fr 1fr; } .metric.project { grid-column: 1 / -1; } .foot { align-items: flex-end; } }
- </style>
- <section class="card" aria-label="MSO workflow progress">
- <div class="head">
- <div class="mark" aria-hidden="true">M</div>
- <div class="title"><h2>MSO workflow</h2><p class="intent" id="intent">Preparing workflow…</p></div>
- <span class="status active" id="state">ACTIVE</span>
- </div>
- <div class="meta">
- <div class="metric project"><span>Project</span><strong id="project">—</strong></div>
- <div class="metric"><span>Elapsed</span><strong id="elapsed">0s</strong></div>
- <div class="metric"><span>Steps</span><strong id="count">0</strong></div>
- </div>
- <div class="steps">
- <div class="steps-head"><strong>Recent progress</strong><span id="updated">waiting</span></div>
- <ol id="step-list"></ol><div class="empty" id="empty">Workflow initialized. Tool progress will appear here.</div>
- </div>
- <div class="foot">
- <span class="connection" id="connection">Live status</span>
- <div class="actions"><button type="button" id="refresh">Refresh</button>${openInMsoControls("primary", "/assistant/mcp")}</div>
- </div>
- </section>
- <script>
- (() => {
- const stateEl = document.getElementById("state");
- const intentEl = document.getElementById("intent");
- const projectEl = document.getElementById("project");
- const elapsedEl = document.getElementById("elapsed");
- const countEl = document.getElementById("count");
- const listEl = document.getElementById("step-list");
- const emptyEl = document.getElementById("empty");
- const updatedEl = document.getElementById("updated");
- const connectionEl = document.getElementById("connection");
- const refreshButton = document.getElementById("refresh");
- let workflowId = "";
- let startedAt = "";
- let active = true;
- let timer = 0;
- const pending = new Map();
- let nextRequestId = 1;
+export { MSO_BLOCK_URI, MSO_PAGE_URI };
+export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
- function safeText(value, fallback = "—") {
- return typeof value === "string" && value.trim() ? value.trim() : fallback;
- }
- function formatDuration(ms) {
- const total = Math.max(0, Math.floor(Number(ms) || 0));
- if (total < 1000) return total + "ms";
- const seconds = Math.floor(total / 1000);
- if (seconds < 60) return seconds + "s";
- const minutes = Math.floor(seconds / 60);
- return minutes + "m " + (seconds % 60) + "s";
- }
- function elapsedMs() {
- const parsed = Date.parse(startedAt);
- return Number.isFinite(parsed) ? Math.max(0, Date.now() - parsed) : 0;
- }
- function render(data) {
- if (!data || typeof data !== "object") return;
- const workflow = data.workflow && typeof data.workflow === "object" ? data.workflow : data;
- workflowId = safeText(workflow.workflowId || workflow.id || data.workflowId, workflowId);
- startedAt = safeText(workflow.startedAt || data.startedAt, startedAt);
- if (typeof data.active === "boolean") active = data.active;
- intentEl.textContent = safeText(workflow.intent || data.intent, "Workflow initialized");
- const bootstrapProject = data.bootstrap && data.bootstrap.project && typeof data.bootstrap.project === "object" ? (data.bootstrap.project.path || data.bootstrap.project.hint) : "";
- projectEl.textContent = safeText(workflow.project || data.project || bootstrapProject, "Not specified");
- const steps = Array.isArray(data.steps) ? data.steps : (Array.isArray(workflow.steps) ? workflow.steps : []);
- countEl.textContent = String(Number.isFinite(data.stepCount) ? data.stepCount : steps.length);
- stateEl.textContent = active ? "ACTIVE" : "CLOSED";
- stateEl.className = "status " + (active ? "active" : "closed");
- listEl.textContent = "";
- const recent = steps.slice(-7).reverse();
- emptyEl.hidden = recent.length > 0;
- for (const step of recent) {
- const li = document.createElement("li");
- const dot = document.createElement("span");
- dot.className = "dot " + safeText(step.state, "completed");
- const tool = document.createElement("span");
- tool.className = "tool";
- tool.textContent = safeText(step.tool, "tool");
- const duration = document.createElement("span");
- duration.className = "duration";
- duration.textContent = step.durationMs == null ? safeText(step.state, "") : formatDuration(step.durationMs);
- li.append(dot, tool, duration);
- listEl.append(li);
- }
- updatedEl.textContent = "updated now";
- elapsedEl.textContent = formatDuration(Number(data.elapsedMs) || elapsedMs());
- if (!active) stopPolling();
- }
- function postMessageCall(name, args) {
- const id = nextRequestId++;
- window.parent.postMessage({ jsonrpc: "2.0", id, method: "tools/call", params: { name, arguments: args } }, "*");
- return new Promise((resolve, reject) => {
- pending.set(id, { resolve, reject });
- window.setTimeout(() => {
- const request = pending.get(id);
- if (!request) return;
- pending.delete(id);
- reject(new Error("status timeout"));
- }, 8000);
- });
- }
- async function callStatus() {
- if (!workflowId || !active || document.visibilityState === "hidden") return;
- refreshButton.disabled = true;
- try {
- const result = window.openai && typeof window.openai.callTool === "function"
- ? await window.openai.callTool("workflow_status", { workflow_id: workflowId })
- : await postMessageCall("workflow_status", { workflow_id: workflowId });
- const payload = result && result.structuredContent ? result.structuredContent : result;
- render(payload);
- connectionEl.textContent = active ? "Live status" : "Workflow closed";
- } catch (_) {
- connectionEl.textContent = "Status refresh unavailable";
- } finally {
- refreshButton.disabled = false;
- }
- }
- function startPolling() {
- stopPolling();
- if (!active) return;
- timer = window.setInterval(callStatus, 4000);
- }
- function stopPolling() {
- if (timer) window.clearInterval(timer);
- timer = 0;
- }
- function readHostOutput() {
- const output = window.openai && window.openai.toolOutput;
- if (output) render(output);
- }
- window.addEventListener("message", (event) => {
- if (event.source !== window.parent) return;
- const message = event.data;
- if (!message || message.jsonrpc !== "2.0") return;
- if (message.id !== undefined && pending.has(message.id)) {
- const request = pending.get(message.id);
- pending.delete(message.id);
- if (message.error) request.reject(message.error); else request.resolve(message.result);
- return;
- }
- if (message.method === "ui/notifications/tool-result" && message.params && message.params.structuredContent) {
- render(message.params.structuredContent);
- }
- }, { passive: true });
- window.addEventListener("openai:set_globals", readHostOutput, { passive: true });
- refreshButton.addEventListener("click", callStatus);
- ${OPEN_IN_MSO_SCRIPT}
- const clock = window.setInterval(() => { elapsedEl.textContent = formatDuration(elapsedMs()); }, 1000);
- window.addEventListener("pagehide", () => { stopPolling(); window.clearInterval(clock); }, { once: true });
- readHostOutput();
- startPolling();
- })();
- </script>
-</main>`;
+// Read-only aliases keep already-cached ChatGPT action descriptors functional
+// across the UI-contract migration. They are intentionally not advertised by
+// resources/list: the public product contract has exactly Block and Page.
+export const LEGACY_WORKFLOW_PROGRESS_URI = "ui://mso/workflow-progress-v3.html";
+export const LEGACY_SURFACE_URI = "ui://mso/surface-v5.html";
export type McpUiResource = {
uri: string;
@@ -210,26 +19,19 @@ export type McpUiResource = {
_meta: Record<string, unknown>;
};
-function workflowResourceMeta(): Record<string, unknown> {
- return widgetResourceMeta("Authoritative MSO workflow progress card. It shows only high-level workflow state and recent tool outcomes; do not repeat the card contents verbatim.");
-}
-
-const RESOURCES: readonly McpUiResource[] = [
- {
- uri: WORKFLOW_PROGRESS_URI,
- name: "MSO workflow progress",
- description: "Compact live progress for an authenticated MSO workflow.",
- mimeType: MCP_APP_MIME_TYPE,
- text: workflowProgressHtml,
- _meta: workflowResourceMeta(),
- },
- MSO_SURFACE_RESOURCE,
-];
+const RESOURCES: readonly McpUiResource[] = [MSO_BLOCK_RESOURCE, MSO_PAGE_RESOURCE];
+const LEGACY_ALIASES = new Map<string, McpUiResource>([
+ [LEGACY_WORKFLOW_PROGRESS_URI, MSO_BLOCK_RESOURCE],
+ [LEGACY_SURFACE_URI, MSO_PAGE_RESOURCE],
+]);
export function listUiResources() {
return RESOURCES.map(({ uri, name, description, mimeType }) => ({ uri, name, description, mimeType }));
}
export function readUiResource(uri: string): McpUiResource | undefined {
- return RESOURCES.find((resource) => resource.uri === uri);
+ const canonical = RESOURCES.find((resource) => resource.uri === uri);
+ if (canonical) return canonical;
+ const legacy = LEGACY_ALIASES.get(uri);
+ return legacy ? { ...legacy, uri } : undefined;
}
diff --git a/lib/mcp/ui-surface-script.ts b/lib/mcp/ui-surface-script.ts
index 6ecd3461..a52bdff2 100644
--- a/lib/mcp/ui-surface-script.ts
+++ b/lib/mcp/ui-surface-script.ts
@@ -12,6 +12,7 @@ const BROWSER_CATALOG = SURFACE_APPS.map((app) => ({
startPath: app.startPath,
renderer: app.renderer,
presentation: app.presentation,
+ environment: app.environment,
sandbox: app.sandbox ?? "",
reason: app.reason ?? "",
}));
@@ -50,7 +51,7 @@ async function displayMode(mode){
try{if(!window.openai||typeof window.openai.requestDisplayMode!=="function")throw new Error("unsupported");await window.openai.requestDisplayMode({mode})}catch(_){modeEl.textContent=mode+" unavailable"}
}
function persistRoute(){
- try{if(window.openai&&typeof window.openai.setWidgetState==="function")window.openai.setWidgetState({modelContent:"MSO Surface: "+current.route,privateContent:{route:current.route},imageIds:[]})}catch(_){}
+ try{if(window.openai&&typeof window.openai.setWidgetState==="function")window.openai.setWidgetState({modelContent:"MSO Page: "+current.route,privateContent:{route:current.route},imageIds:[]})}catch(_){}
}
function rpcCall(name,args){
const id=nextRpcId++;window.parent.postMessage({jsonrpc:"2.0",id,method:"tools/call",params:{name,arguments:args}},"*");
@@ -61,15 +62,15 @@ function nav(route,extra={}){
if(!validRoute(route))return;
current={route,kind:route==="/"?"home":"loading",title:"MSO",openPath:"/assistant/mcp",catalog:current.catalog,...extra};render();
if(route==="/")return;
- rpcCall("render_mso_surface",{route,...(extra.project?{project:extra.project}:{}),...(extra.sha?{sha:extra.sha}:{})}).then(result=>{const value=unbox(result);if(value&&typeof value==="object"){current=value;render()}}).catch(showError)
+ rpcCall("render_mso_page",{route,...(extra.project?{project:extra.project}:{}),...(extra.sha?{sha:extra.sha}:{})}).then(result=>{const value=unbox(result);if(value&&typeof value==="object"){current=value;render()}}).catch(showError)
}
-function showError(error){clear(body);const box=el("div","notice");const inner=el("div");inner.append(el("h3","","Surface unavailable"),el("p","error",error&&error.message?error.message:"The requested surface could not be loaded."));box.append(inner);body.append(box)}
+function showError(error){clear(body);const box=el("div","notice");const inner=el("div");inner.append(el("h3","","Page unavailable"),el("p","error",error&&error.message?error.message:"The requested page could not be loaded."));box.append(inner);body.append(box)}
function renderHome(){
- const root=el("div","home");const hero=el("section","hero");hero.append(el("h2","","MSO Surface"),el("p","","ChatGPT is another MSO presentation target. Open a native operator view or a reviewed live demo without leaving the conversation."));root.append(hero);
- root.append(el("div","section-title","Native surfaces"));const native=el("div","grid");
+ const root=el("div","home");const hero=el("section","hero");hero.append(el("h2","","MSO Page"),el("p","","ChatGPT is another MSO presentation target. Open a native operator view or a reviewed live demo without leaving the conversation."));root.append(hero);
+ root.append(el("div","section-title","Native pages"));const native=el("div","grid");
for(const item of [{route:"/monitor",title:"System Monitor",desc:"Live bounded host status."},{route:"/project",title:"Project",desc:"Project snapshot and Git state."},{route:"/diff",title:"Diff",desc:"Review project changes."},{route:"/browser",title:"Remote Browser",desc:"Fallback seam for sites that deny framing."}]){const card=button("",()=>nav(item.route),"card");card.append(el("strong","",item.title),el("span","",item.desc));native.append(card)}root.append(native);
- root.append(el("div","section-title","Reviewed app demos"));const apps=el("div","grid");
- for(const app of SAFE_APPS){const card=button("",()=>nav("/apps/"+encodeURIComponent(app.id)),"card");card.append(el("strong","",app.title),el("span","",app.description),el("span","tag",app.renderer));apps.append(card)}root.append(apps);body.append(root)
+ root.append(el("div","section-title","Reviewed development and production pages"));const apps=el("div","grid");
+ for(const app of SAFE_APPS){const card=button("",()=>nav("/apps/"+encodeURIComponent(app.id)),"card");card.append(el("strong","",app.title),el("span","",app.description),el("span","tag",app.environment+" · "+app.renderer));apps.append(card)}root.append(apps);body.append(root)
}
function renderMonitor(){
const stage=stageBase("Live bounded VPS status");const metrics=el("div","metrics");for(const name of ["CPU","Memory","Disk"]){const m=el("div","metric");m.append(el("span","",name),el("strong","","…"));metrics.append(m)}stage.content.append(metrics);const list=el("div","list");stage.content.append(list);body.append(stage.root);
@@ -83,12 +84,12 @@ function renderProjectPrompt(kind){const box=el("div","notice");const inner=el("
function appendLine(list,label,value){const row=el("div","line");row.append(el("span","",label),el("strong","mono",value==null?"—":value));list.append(row)}
function stageBase(subtitle){const root=el("div","stage"),head=el("div","stage-head"),content=el("div");head.append(button("←",()=>nav("/"),"back"));const t=el("div","stage-title");t.append(el("strong","",current.title),el("span","",subtitle));head.append(t);root.append(head,content);return{root,content}}
function renderApp(){
- const raw=current.app,safe=safeAppResult(raw);if(!safe){showError(new Error("The app result is not in the reviewed MSO Surface registry."));return}const stage=stageBase(safe.renderer==="iframe"?"Live app demo":"Remote-browser fallback");body.append(stage.root);openPath(safe.renderer==="remote"?"/browser":"/assistant/mcp");
+ const raw=current.app,safe=safeAppResult(raw);if(!safe){showError(new Error("The app result is not in the reviewed MSO Page registry."));return}const stage=stageBase(safe.renderer==="iframe"?"Live app demo":"Remote-browser fallback");body.append(stage.root);openPath(safe.renderer==="remote"?"/browser":"/assistant/mcp");
if(safe.renderer==="iframe"){const wrap=el("div","frame-wrap"),frame=document.createElement("iframe");frame.title=safe.title+" live demo";frame.src=safe.url;frame.setAttribute("sandbox",safe.sandbox);frame.referrerPolicy="no-referrer";frame.allow="fullscreen";wrap.append(frame);stage.content.append(wrap);return}
const box=el("div","notice"),inner=el("div");inner.append(el("h3","",safe.title+" protects itself from framing"),el("p","",safe.reason||"This app is not allowlisted for nested framing. MSO preserves the app's own frame policy instead of stripping it."));const row=el("div","row");row.append(button("Open Remote Browser",()=>openMso(),"primary"));if(window.openai&&typeof window.openai.sendFollowUpMessage==="function")row.append(button("Ask ChatGPT to continue",()=>window.openai.sendFollowUpMessage({prompt:"Continue this demo using the MSO remote-browser fallback for "+safe.title+"."})));inner.append(row);box.append(inner);stage.content.append(box);if(safe.presentation==="pip")pipBtn.hidden=false
}
function renderBrowser(){const box=el("div","notice"),inner=el("div");inner.append(el("h3","","Remote Browser seam"),el("p","","Sites that deny iframe embedding stay isolated. MSO can continue them through Camoufox without exposing its VNC password or authenticated viewer URL to this widget."));const row=el("div","row");row.append(button("Open MSO Browser",()=>openMso(),"primary"));inner.append(row);box.append(inner);body.append(box);openPath("/browser")}
-function render(){clear(body);titleEl.textContent=text(current.title,"MSO Surface");routeEl.textContent=text(current.route,"/");openPath(text(current.openPath,"/assistant/mcp"));persistRoute();if(current.kind==="home")renderHome();else if(current.kind==="monitor")renderMonitor();else if(current.kind==="project")renderProject("project");else if(current.kind==="diff")renderProject("diff");else if(current.kind==="app")renderApp();else if(current.kind==="browser")renderBrowser();else body.append(el("div","loading","Loading MSO Surface…"))}
+function render(){clear(body);titleEl.textContent=text(current.title,"MSO Page");routeEl.textContent=text(current.route,"/");openPath(text(current.openPath,"/assistant/mcp"));persistRoute();if(current.kind==="home")renderHome();else if(current.kind==="monitor")renderMonitor();else if(current.kind==="project")renderProject("project");else if(current.kind==="diff")renderProject("diff");else if(current.kind==="app")renderApp();else if(current.kind==="browser")renderBrowser();else body.append(el("div","loading","Loading MSO Page…"))}
function readOutput(){const value=window.openai&&window.openai.toolOutput;if(value&&typeof value==="object"){current=value;render()}}
window.addEventListener("message",event=>{if(event.source!==window.parent)return;const msg=event.data;if(!msg||msg.jsonrpc!=="2.0")return;if(msg.id!==undefined&&pending.has(msg.id)){const req=pending.get(msg.id);pending.delete(msg.id);msg.error?req.reject(msg.error):req.resolve(msg.result);return}if(msg.method==="ui/notifications/tool-result"&&msg.params&&msg.params.structuredContent){current=msg.params.structuredContent;render()}},{passive:true});
window.addEventListener("openai:set_globals",()=>{applyHostGlobals();readOutput()},{passive:true});
diff --git a/lib/mcp/ui-surface.ts b/lib/mcp/ui-surface.ts
index a9ca81f0..26d4ff86 100644
--- a/lib/mcp/ui-surface.ts
+++ b/lib/mcp/ui-surface.ts
@@ -4,14 +4,14 @@ import { surfaceFrameDomains } from "./surface-catalog";
import { MSO_SURFACE_SCRIPT } from "./ui-surface-script";
import { MSO_SURFACE_STYLE } from "./ui-surface-style";
-export const MSO_SURFACE_URI = "ui://mso/surface-v5.html";
+export const MSO_PAGE_URI = "ui://mso/page-v1.html";
const MIME = "text/html;profile=mcp-app";
-const html = String.raw`<main class="surface" aria-label="MSO Surface">
+const html = String.raw`<main class="surface" aria-label="MSO Page">
<style>${MSO_SURFACE_STYLE}</style>
<header class="bar">
<div class="brand" aria-hidden="true">M</div>
- <div class="heading"><strong id="surface-title">MSO Surface</strong><span id="surface-route">/</span></div>
+ <div class="heading"><strong id="surface-title">MSO Page</strong><span id="surface-route">/</span></div>
<span class="mode-badge" id="surface-mode">inline</span>
<div class="tools">
<button type="button" id="surface-home" class="optional">Home</button>
@@ -20,18 +20,18 @@ const html = String.raw`<main class="surface" aria-label="MSO Surface">
${openInMsoControls("primary", "/assistant/mcp")}
</div>
</header>
-<section class="body" id="surface-body"><div class="loading">Loading MSO Surface…</div></section>
+<section class="body" id="surface-body"><div class="loading">Loading MSO Page…</div></section>
<script>(()=>{${OPEN_IN_MSO_SCRIPT}${MSO_SURFACE_SCRIPT}})();</script>
</main>`;
-export const MSO_SURFACE_RESOURCE = {
- uri: MSO_SURFACE_URI,
- name: "MSO Surface",
- description: "Universal secure MSO presentation target for native operator views and explicitly reviewed app targets inside ChatGPT.",
+export const MSO_PAGE_RESOURCE = {
+ uri: MSO_PAGE_URI,
+ name: "MSO Page",
+ description: "Full-page MSO presentation target for native operator views and explicitly reviewed development or production app embeds.",
mimeType: MIME,
text: html,
_meta: widgetResourceMeta(
- "Interactive MSO Surface. It renders native MSO views and exact-origin reviewed app demos. Nested frames are limited to explicit CSP frame domains and dedicated embed routes; arbitrary HTML and URLs are never accepted from the model.",
+ "Interactive MSO Page. It renders native operator views and exact-origin reviewed development or production targets. Nested frames are limited to explicit CSP frame domains and dedicated embed routes; arbitrary HTML and URLs are never accepted from the model.",
{ frameDomains: surfaceFrameDomains() },
),
} as const;
diff --git a/scripts/lib/mcp-catalog.mjs b/scripts/lib/mcp-catalog.mjs
index 90e019b9..c06a17ce 100644
--- a/scripts/lib/mcp-catalog.mjs
+++ b/scripts/lib/mcp-catalog.mjs
@@ -1,7 +1,7 @@
import { readFileSync, readdirSync } from "node:fs";
import { join } from "node:path";
-export const APP_ONLY_MCP_TOOLS = new Set(["workflow_status"]);
+export const APP_ONLY_MCP_TOOLS = new Set(["workflow_status", "render_mso_surface"]);
const TOOL_MODULE_NAME = /^tools-[A-Za-z0-9-]+\.ts$/;
const SCOPES = ["read", "write", "exec"];