poseref 0.1.1 → 0.1.2

package/README.md

@@ -20,6 +20,8 @@ npx poseref setup
 終わったら Claude Code / Codex を起動し直し、「PoseRef で、椅子に座って頬杖をつくポーズを斜め前から撮って」のように頼んでください。
 エージェントが最初に PoseRef のツールを使ったときに、PoseRef が起動してブラウザで画面が開きます。
 3D の描画はブラウザで行うので、このタブは開いたままにしてください。ヘッダーに「AI連携: 接続中」と表示されていれば準備できています。
+タブを閉じてしまっても、次にツールを使ったときに開き直します（ユーザーがわざと閉じた直後に何度も開かないよう、自動で開くのは 60 秒に 1 回までです）。
+「PoseRef を開いて」と頼むと、エージェントが `open_poseref` で画面を開きます。すでにタブが開いていれば、新しいタブは増やしません。
 
 登録するコマンドはバージョンを固定しています（`npx -y poseref@<バージョン> mcp`）。新しい版が公開されても、知らないうちに別のコードが動くことはありません。
 更新するときは `npx poseref@latest setup` を実行し直してください。
@@ -42,8 +44,9 @@ npx poseref stop   # 起動中の PoseRef を止める
 
 ### Claude Code と Codex の確認
 
-Codex は、読み取り専用ではない MCP ツールを呼ぶたびに承認を求めます。`set_scene` と `reach` は PoseRef の画面だけを変える操作で、
-「元に戻す」で取り消せるので、`npx poseref setup` はこの 2 つを承認なしで実行する設定を `~/.codex/config.toml` に追記します。
+Codex は、読み取り専用ではない MCP ツールを呼ぶたびに承認を求めます。`set_scene` と `reach` は PoseRef の画面だけを変え、
+「元に戻す」で取り消せる操作で、`open_poseref` は PoseRef の画面を開くだけの操作です。そのため `npx poseref setup` は、この 3 つを承認なしで実行する設定を
+`~/.codex/config.toml` に追記します。
 追記の前に同じ場所へバックアップを作り、Codex が設定を読めなくなった場合は元に戻します。
 この設定がないと、ポーズを直すたびに承認することになり、`codex exec` のような非対話の実行では `set_scene` がキャンセルされます。
 
@@ -54,6 +57,7 @@ Claude Code もツールを呼ぶたびに許可を求めることがありま
 
 | ツール | 内容 |
 | --- | --- |
+| `open_poseref` | PoseRef が止まっていれば起動し、ブラウザで画面を開く。タブがすでに開いていれば何もしない |
 | `get_pose_spec` | ボーンの軸と符号の決まり、接地、カメラ、プリセットの実例をまとめた説明書を返す。内容はコードの定数から生成される |
 | `get_scene` | 現在のポーズ・キャラクターの向きと位置・カメラ・アスペクト比を JSON で返す |
 | `set_scene` | ポーズ・キャラクター・カメラ・アスペクト比を適用する。ポーズを指定したときは、体の最下点が床にちょうど着くよう腰の高さを自動で合わせる（ジャンプなどは `pose.ground: false` で無効にできる）。未知のボーン名や範囲外の値は、何も適用せずにエラーを返す |
@@ -129,6 +133,9 @@ approval_mode = "approve"
 
 [mcp_servers.poseref-dev.tools.reach]
 approval_mode = "approve"
+
+[mcp_servers.poseref-dev.tools.open_poseref]
+approval_mode = "approve"
 ```
 
 npm への公開は `npm publish` で行います。`prepublishOnly` でビルドとテストが走ります。

package/dist-server/cli.js

@@ -18,6 +18,9 @@ import { createInterface } from "node:readline/promises";
 var REQUEST_TIMEOUT_MS$1 = 2e4;
 /** Thrown when no browser tab is connected; the message is meant for the agent to relay. */
 var NoBrowserError = class extends Error {};
+function noBrowserError(url) {
+	return new NoBrowserError(`No PoseRef browser tab is connected. Call open_poseref, or ask the user to open ${url} in a browser, then retry. If that page does not load, PoseRef is not running: the user can start it with \`npx poseref\`.`);
+}
 /**
 * Tracks the PoseRef browser tabs connected over WebSocket and forwards agent
 * requests to one of them. The tab that most recently gained focus wins, so
@@ -27,9 +30,9 @@ var BrowserBridge = class {
 	tabs = [];
 	pending = /* @__PURE__ */ new Map();
 	nextId = 1;
-	appUrl;
-	constructor(appUrl) {
-		this.appUrl = appUrl;
+	opener;
+	constructor(opener) {
+		this.opener = opener;
 	}
 	get connectedTabs() {
 		return this.tabs.length;
@@ -40,9 +43,16 @@ var BrowserBridge = class {
 		socket.on("close", () => this.detach(socket));
 		socket.on("error", () => socket.close());
 	}
+	async open(automatic) {
+		return {
+			...await this.opener.ensureTab(automatic, async () => this.tabs.length),
+			url: this.opener.url,
+			startedServer: false
+		};
+	}
 	request(method, params) {
 		const socket = this.tabs[this.tabs.length - 1];
-		if (!socket) return Promise.reject(new NoBrowserError(`No PoseRef browser tab is connected. Ask the user to open ${this.appUrl} in a browser, then retry. If that page does not load, PoseRef is not running: the user can start it with \`npx poseref\`.`));
+		if (!socket) return Promise.reject(noBrowserError(this.opener.url));
 		const id = this.nextId++;
 		const message = {
 			type: "request",
@@ -1837,6 +1847,7 @@ var DEFAULT_VIEW_SIZE = 480;
 /** A contact within 2 cm reads as touching in the render. */
 var REACHED_WITHIN = .02;
 var INSTRUCTIONS = `PoseRef controls a posable mannequin and camera in the user's browser to build pose and composition reference images.
+The tools open the PoseRef page in the browser by themselves when no tab is connected. When the user asks to open or show PoseRef, call open_poseref.
 Call get_pose_spec once before your first set_scene: it explains the bone axes and sign conventions, which are easy to get wrong.
 Before posing, decide which way the character acts (a target, a direction) and keep that direction across the picture so the action reads in silhouette; aiming, throwing and swinging are done side-on (see the spec's "Composition and readability").
 Then loop: set_scene -> render_views -> compare with the request and check the silhouette from the 'current' view -> adjust. When the request has body parts touching (hand on hip, elbow on knee, hands together), set the rough pose first and then place the contacts with reach (inverse kinematics) instead of guessing angles; confirm with get_joint_positions and only report contact the numbers show. set_scene puts the body on the floor automatically. Stop after two or three rounds when the pose is roughly right; the user fine-tunes by hand and can undo your changes in the app.`;
@@ -1857,6 +1868,20 @@ function compactScene(scene) {
 		}
 	});
 }
+/**
+* Runs a browser request. When no tab is connected, opens the page (the bridge
+* rate-limits automatic opening) and tries once more, so a closed tab does not
+* leave the agent stuck asking the user.
+*/
+async function withTab(bridge, call) {
+	try {
+		return await call();
+	} catch (error) {
+		if (!(error instanceof NoBrowserError)) throw error;
+		if ((await bridge.open(true)).tabs === 0) throw error;
+		return await call();
+	}
+}
 function failure(error) {
 	return {
 		content: [{
@@ -1895,7 +1920,7 @@ function createPoseRefMcpServer(bridge) {
 		annotations: { readOnlyHint: true }
 	}, async () => {
 		try {
-			return text(compactScene(await bridge.request("getScene", {})));
+			return text(compactScene(await withTab(bridge, () => bridge.request("getScene", {}))));
 		} catch (error) {
 			return failure(error);
 		}
@@ -1906,10 +1931,10 @@ function createPoseRefMcpServer(bridge) {
 		inputSchema: sceneSchema
 	}, async (scene) => {
 		try {
-			const { scene: applied, groundShift } = await bridge.request("setScene", {
+			const { scene: applied, groundShift } = await withTab(bridge, () => bridge.request("setScene", {
 				version: 1,
 				...scene
-			});
+			}));
 			return text(`Applied.${groundShift === null ? "" : groundShift === 0 ? " Already resting on the floor." : ` Grounded: hips moved ${groundShift > 0 ? "up" : "down"} by ${Math.abs(groundShift)} m so the lowest body point rests on the floor.`} Current scene (bones not listed are 0): ${compactScene(applied)}`);
 		} catch (error) {
 			return failure(error);
@@ -1922,10 +1947,10 @@ function createPoseRefMcpServer(bridge) {
 		annotations: { readOnlyHint: true }
 	}, async ({ views, size }) => {
 		try {
-			const result = await bridge.request("renderViews", {
+			const result = await withTab(bridge, () => bridge.request("renderViews", {
 				views: views ?? [...DEFAULT_VIEWS],
 				size: size ?? DEFAULT_VIEW_SIZE
-			});
+			}));
 			const path = await saveRender(result.pngBase64);
 			return { content: [{
 				type: "image",
@@ -1946,7 +1971,7 @@ function createPoseRefMcpServer(bridge) {
 		annotations: { readOnlyHint: true }
 	}, async ({ pairs }) => {
 		try {
-			const report = await bridge.request("getJoints", {});
+			const report = await withTab(bridge, () => bridge.request("getJoints", {}));
 			const distances = (pairs ?? []).map(([a, b]) => {
 				const p = report.joints[a];
 				const q = report.joints[b];
@@ -1972,7 +1997,7 @@ function createPoseRefMcpServer(bridge) {
 		inputSchema: reachSchema
 	}, async ({ goals, ground }) => {
 		try {
-			const scene = await bridge.request("getScene", {});
+			const scene = await withTab(bridge, () => bridge.request("getScene", {}));
 			const frame = {
 				bones: scene.pose.bones,
 				rootOffset: scene.pose.rootOffset,
@@ -1986,14 +2011,14 @@ function createPoseRefMcpServer(bridge) {
 			}
 			const result = solveIk(frame, goals, chains);
 			const bones = Object.fromEntries(result.changed.map((bone) => [bone, result.bones[bone]]));
-			const { groundShift } = await bridge.request("setScene", {
+			const { groundShift } = await withTab(bridge, () => bridge.request("setScene", {
 				version: 1,
 				pose: {
 					mode: "merge",
 					bones,
 					ground
 				}
-			});
+			}));
 			const lines = result.goals.map((goal) => `- ${goal.effector}: ${goal.error <= REACHED_WITHIN ? "reached" : "NOT reached"}, ${goal.error} m from the target (rotated ${goal.chain.join(", ")})`);
 			const advice = result.goals.some((goal) => goal.error > REACHED_WITHIN) ? "\nA target out of reach leaves the limb pointing at it but short. Move the body closer first (lean the chest, bend the legs), add a parent bone such as chest to that goal's chain, or add a goal that moves the other body part toward this one." : "";
 			const grounding = groundShift ? `\nGrounded: hips moved ${groundShift > 0 ? "up" : "down"} by ${Math.abs(groundShift)} m.` : "";
@@ -2002,6 +2027,27 @@ function createPoseRefMcpServer(bridge) {
 			return failure(error);
 		}
 	});
+	server.registerTool("open_poseref", {
+		title: "Open PoseRef",
+		description: "Starts PoseRef if it is not running and opens it in the user's browser. Does nothing when a PoseRef tab is already open. Use it when the user asks to open or show PoseRef; the other tools also open the page on their own when no tab is connected.",
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async () => {
+		try {
+			const result = await bridge.open(false);
+			const started = result.startedServer ? "Started the PoseRef server. " : "";
+			if (result.tabs > 0 && !result.opened) return text(`${started}PoseRef is already open at ${result.url} (${result.tabs} tab${result.tabs === 1 ? "" : "s"}).`);
+			if (result.tabs > 0) return text(`${started}Opened PoseRef at ${result.url}.`);
+			if (result.disabled) return text(`${started}Did not open a browser because POSEREF_NO_OPEN is set. Ask the user to open ${result.url}.`);
+			return text(`${started}Opened ${result.url}, but the page has not connected yet. Ask the user to check the browser window.`);
+		} catch (error) {
+			return failure(error);
+		}
+	});
 	return server;
 }
 /** Stateless Streamable HTTP handler: every request gets a fresh McpServer bound to the shared bridge. */
@@ -2009,6 +2055,79 @@ function createPoseRefMcpHandler(bridge) {
 	return createMcpHandler(() => createPoseRefMcpServer(bridge));
 }
 //#endregion
+//#region server/browser.ts
+/**
+* Opens the PoseRef page in the default browser. The URL is always one PoseRef
+* built itself (http://127.0.0.1:<port>, or http://localhost:<port> for the Vite
+* dev server), and no shell is involved, so nothing from outside can reach the
+* command line.
+*/
+function openBrowser(url, log) {
+	if (!/^http:\/\/(?:127\.0\.0\.1|localhost):\d+\/?$/.test(url)) throw new Error(`Refusing to open unexpected URL: ${url}`);
+	const [command, args] = process.platform === "win32" ? ["explorer.exe", [url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+	const child = spawn(command, args, {
+		detached: true,
+		stdio: "ignore",
+		windowsHide: true
+	});
+	child.on("error", () => log(`ブラウザで ${url} を開いてください。`));
+	child.unref();
+}
+//#endregion
+//#region server/opener.ts
+var TAB_WAIT_MS = 2e4;
+var POLL_MS$1 = 300;
+/**
+* Automatic opening (a tool found no tab) happens at most this often, so a user
+* who closes the tab on purpose is not handed a new one on every tool call.
+* An explicit open_poseref call is never throttled.
+*/
+var AUTO_OPEN_COOLDOWN_MS = 6e4;
+var sleep$1 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Decides whether to open the PoseRef page, opens it, and waits for the tab to connect. */
+var PageOpener = class {
+	options;
+	lastAutoOpen = Number.NEGATIVE_INFINITY;
+	constructor(options) {
+		this.options = options;
+	}
+	get url() {
+		return this.options.url;
+	}
+	async ensureTab(automatic, countTabs) {
+		let tabs = await countTabs();
+		if (tabs > 0) return {
+			tabs,
+			opened: false,
+			disabled: false
+		};
+		if (!this.options.enabled) return {
+			tabs,
+			opened: false,
+			disabled: true
+		};
+		if (automatic) {
+			if (Date.now() - this.lastAutoOpen < AUTO_OPEN_COOLDOWN_MS) return {
+				tabs,
+				opened: false,
+				disabled: false
+			};
+			this.lastAutoOpen = Date.now();
+		}
+		(this.options.openPage ?? ((url) => openBrowser(url, this.options.log)))(this.options.url);
+		const deadline = Date.now() + TAB_WAIT_MS;
+		while (tabs === 0 && Date.now() < deadline) {
+			await sleep$1(POLL_MS$1);
+			tabs = await countTabs();
+		}
+		return {
+			tabs,
+			opened: true,
+			disabled: false
+		};
+	}
+};
+//#endregion
 //#region server/app.ts
 var MCP_PATH = "/mcp";
 /** Loopback only: the server drives the user's browser tab and must not be reachable from the network. */
@@ -2053,7 +2172,12 @@ function createPoseRefServer(options) {
 		`http://localhost:${options.port}`,
 		...options.extraOrigins ?? []
 	]);
-	const bridge = new BrowserBridge(appUrl);
+	const bridge = new BrowserBridge(new PageOpener({
+		url: options.pageUrl ?? appUrl,
+		enabled: !process.env.POSEREF_NO_OPEN,
+		log: (message) => process.stderr.write(`${message}\n`),
+		openPage: options.openPage
+	}));
 	const mcp = toNodeHandler(createPoseRefMcpHandler(bridge));
 	const staticRoot = options.staticDir ? resolve(options.staticDir) : null;
 	const validateHost = localhostHostValidation();
@@ -2113,24 +2237,6 @@ function createPoseRefServer(options) {
 	};
 }
 //#endregion
-//#region server/browser.ts
-/**
-* Opens the PoseRef page in the default browser. The URL is always one PoseRef
-* built itself (http://127.0.0.1:<port>), and no shell is involved, so nothing
-* from outside can reach the command line.
-*/
-function openBrowser(url, log) {
-	if (!/^http:\/\/127\.0\.0\.1:\d+\/?$/.test(url)) throw new Error(`Refusing to open unexpected URL: ${url}`);
-	const [command, args] = process.platform === "win32" ? ["explorer.exe", [url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
-	const child = spawn(command, args, {
-		detached: true,
-		stdio: "ignore",
-		windowsHide: true
-	});
-	child.on("error", () => log(`ブラウザで ${url} を開いてください。`));
-	child.unref();
-}
-//#endregion
 //#region server/port.ts
 /** Fixed default so the MCP URL registered with agents stays valid across restarts. */
 var DEFAULT_PORT = 47173;
@@ -2141,7 +2247,6 @@ function resolvePort() {
 //#endregion
 //#region server/remote.ts
 var START_TIMEOUT_MS = 15e3;
-var TAB_WAIT_MS = 2e4;
 var POLL_MS = 300;
 var REQUEST_TIMEOUT_MS = 3e4;
 var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -2157,11 +2262,18 @@ var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var RemoteBridge = class {
 	options;
 	baseUrl;
+	opener;
 	ready = null;
-	browserOpened = false;
+	startedServer = false;
 	constructor(options) {
 		this.options = options;
 		this.baseUrl = `http://127.0.0.1:${options.port}`;
+		this.opener = new PageOpener({
+			url: this.baseUrl,
+			enabled: options.openBrowser,
+			log: options.log,
+			openPage: options.openPage
+		});
 	}
 	async request(method, params) {
 		try {
@@ -2174,6 +2286,21 @@ var RemoteBridge = class {
 			return await this.call(method, params);
 		}
 	}
+	async open(automatic) {
+		this.ready = null;
+		await this.ensureReady();
+		const result = await this.opener.ensureTab(automatic, async () => {
+			const probe = await this.probe();
+			return probe.kind === "poseref" ? probe.tabs : 0;
+		});
+		const startedServer = this.startedServer;
+		this.startedServer = false;
+		return {
+			...result,
+			url: this.baseUrl,
+			startedServer
+		};
+	}
 	ensureReady() {
 		this.ready ??= this.prepare().catch((error) => {
 			this.ready = null;
@@ -2181,21 +2308,18 @@ var RemoteBridge = class {
 		});
 		return this.ready;
 	}
+	/** Makes sure the listener on the port is PoseRef, starting it if nothing is there. */
 	async prepare() {
 		let probe = await this.probe();
 		if (probe.kind === "foreign") throw this.foreignError();
 		if (probe.kind === "absent") {
 			this.options.log("Starting the PoseRef server…");
 			this.options.startServer();
+			this.startedServer = true;
 			probe = await this.waitFor((next) => next.kind !== "absent", START_TIMEOUT_MS);
 			if (probe.kind === "foreign") throw this.foreignError();
 			if (probe.kind === "absent") throw new Error("The PoseRef server did not start. Run `npx poseref start` in a terminal to see why.");
 		}
-		if (this.options.openBrowser && probe.kind === "poseref" && probe.tabs === 0 && !this.browserOpened) {
-			this.browserOpened = true;
-			openBrowser(this.baseUrl, this.options.log);
-			await this.waitFor((next) => next.kind === "poseref" && next.tabs > 0, TAB_WAIT_MS);
-		}
 	}
 	async waitFor(done, timeoutMs) {
 		const deadline = Date.now() + timeoutMs;
@@ -2247,6 +2371,7 @@ var RemoteBridge = class {
 		}
 		const body = await response.json().catch(() => ({}));
 		if (body.ok === true) return body.result;
+		if (response.status === 503) throw noBrowserError(this.baseUrl);
 		if (body.ok === false && body.error) throw new Error(body.error);
 		throw new Error(`The PoseRef server rejected the request (HTTP ${response.status}${body.error ? `: ${body.error}` : ""}).`);
 	}
@@ -2272,8 +2397,15 @@ function spawnDetachedServer(cliPath, log) {
 }
 //#endregion
 //#region server/setup.ts
-/** Tools that change the scene. Codex asks before each call unless they are approved in config.toml. */
-var WRITE_TOOLS = ["set_scene", "reach"];
+/**
+* Tools that are not read-only: two change the scene and open_poseref opens a
+* browser tab. Codex asks before each call unless they are approved in config.toml.
+*/
+var WRITE_TOOLS = [
+	"set_scene",
+	"reach",
+	"open_poseref"
+];
 /**
 * The command agents run to start PoseRef's stdio MCP server. The version is
 * pinned so a later release (or a compromised one) never runs without the user
@@ -2308,7 +2440,7 @@ function appendCodexApprovals(toml, server = "poseref") {
 	};
 	const blocks = added.map((tool) => `[mcp_servers.${server}.tools.${tool}]\napproval_mode = "approve"\n`);
 	return {
-		text: `${toml}${toml.length === 0 || toml.endsWith("\n\n") ? "" : toml.endsWith("\n") ? "\n" : "\n\n"}# Added by \`poseref setup\`: these tools only change the PoseRef tab, and the change can be undone there.
+		text: `${toml}${toml.length === 0 || toml.endsWith("\n\n") ? "" : toml.endsWith("\n") ? "\n" : "\n\n"}# Added by \`poseref setup\`: these tools only change or open the PoseRef tab; scene changes can be undone there.
 ${blocks.join("\n")}`,
 		added: [...added]
 	};
@@ -2421,7 +2553,7 @@ function codexSteps(launch, env, log) {
 			if (!added.ok) throw new Error(`codex mcp add failed${exists ? REMOVED_NOTE : ""}:\n${added.output}`);
 		}
 	}, {
-		describe: `Let ${WRITE_TOOLS.join(" and ")} run without a prompt each time: append approval settings to ${configPath} (a backup is kept next to it)`,
+		describe: `Let ${WRITE_TOOLS.join(", ")} run without a prompt each time: append approval settings to ${configPath} (a backup is kept next to it)`,
 		apply: () => {
 			const { text, added } = appendCodexApprovals(existsSync(configPath) ? readFileSync(configPath, "utf8") : "");
 			if (added.length === 0) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poseref",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Pose and composition reference maker for image-generation AI, with an MCP server so Claude Code and Codex can pose it",
   "keywords": [
     "pose",