canvasight-open

name	canvasight-open
description	Open, reopen, attach, and verify Canvasight's Codex native widget, or explicitly open a browser fallback. Use when the user asks to start Canvasight, open the Canvasight workspace, 打开画布, 打开 Canvasight, 恢复最近项目, attach the current Codex task, or verify whether a native canvas actually became ready.

Canvasight Open

Use this skill to open Canvasight through MCP and verify the real native widget runtime.

Native Open Workflow

1. Read the active task's CODEX_THREAD_ID and current working directory from the shell. Require both a non-empty thread id and an absolute project path; pass them as threadId and projectPath.
2. If the tools are not callable, use tool_search for canvasight open_canvasight await_canvasight_widget_ready render_canvasight_canvas_widget.
3. Call open_canvasight exactly once for this user-level open action, pass the explicit projectPath, and retain the complete provisional result. Use render_canvasight_canvas_widget only as a compatibility alias, never as a second attempt to recover identity. Do not rely on a thread lookup or daemon default to infer the project: an unreadable or archived task must never silently open another folder's .scatter document.
4. Read sessionId and openAttemptId from the retained result's structuredContent. Tool completion is not evidence that the canvas rendered.
5. Immediately call await_canvasight_widget_ready with those two ids and the same threadId. Treat these two MCP calls as one indivisible user-level open action. Do not call open_canvasight again to recover sessionId or openAttemptId. If the first result or either id was lost, mark the opening unverified, do not reopen, and route diagnosis through canvasight-troubleshooting.
6. Report the canvas as opened or ready only when the result has status: "ready", verified: true, displayMode: "fullscreen", and all of reactMounted, projectHydrated, canvasRendered, and canvasVisible set to true.
7. For timeout, failed, missing identity/evidence, or a non-fullscreen instance, report openAttemptId, widgetInstanceId, stage, and error, keep the native open result unverified, and route diagnosis through canvasight-troubleshooting.

Do not replace step 5 with resource reads, daemon health, build output, MCP smoke tests, browser fallback, or visual assumptions. Do not loop on ready timeouts or silently open localhost.

opened = open_canvasight({ threadId, projectPath })
sessionId = opened.structuredContent.sessionId
openAttemptId = opened.structuredContent.openAttemptId
ready = await_canvasight_widget_ready({ sessionId, openAttemptId, threadId })

Recovery And Fallback

• When a native tool returns Transport closed, report canvasight_mcp_transport_closed and check the installed plugin state. If the plugin version changed while Codex Desktop was running, reload/restart the Codex host before creating and tagging a new task; a new task alone can retain the old app-level registry. Browser fallback is not a native recovery.
• When neither the native open tool nor await_canvasight_widget_ready is available after tool_search, report the missing capability. After an install or upgrade, require a Codex host reload/restart followed by a newly created and newly tagged task. Do not claim readiness.
• Use list_canvasight_recent_projects and open_canvasight_recent_project to reopen a recent project, then apply the same instance-bound ready gate with its returned sessionId and openAttemptId.
• Use open_canvasight_browser_fallback only when the user explicitly requests fallback or when diagnosing the browser surface. It queues Run payloads for await_canvasight_run after an explicit thread claim and never satisfies native-widget readiness.
• Call close_canvasight only for a specific session that is no longer needed. It does not stop the project daemon.

After verified readiness, treat the project as active Canvasight context. Route later structured canvas-writing requests to canvasight-graph-writer; keep small direct commands and Run payloads on their normal paths.

Read references/open-workflow.md for the detailed contract and failure handling.