cozyclay 1.7.0 → 1.7.1

package/bin/agent/codex-client.mjs

@@ -0,0 +1,295 @@
+// Codex backend client (issue #124): a zero-dependency Node 20+ module that
+// talks to https://chatgpt.com/backend-api/codex with a ChatGPT OAuth bearer.
+//
+// Facts verified against the live backend (2026-09-06):
+// - POST /responses MUST send store:false, stream:true and an array `input`;
+//   the backend rejects max_output_tokens, previous_response_id, background,
+//   store:true and stream:false — so those keys are never sent.
+// - Reasoning items may only be replayed verbatim (never fabricated).
+// - The account allows ~1 concurrent request: parallel calls get 429 with
+//   Retry-After 5-8s → every request is serialized and 429s sleep Retry-After.
+
+const CODEX_BASE = "https://chatgpt.com/backend-api/codex";
+const CLIENT_VERSION = "0.153.4";
+
+function defaultSleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Normalizes missing/absent header values. */
+function readHeader(headersLike, name) {
+	if (!headersLike) return undefined;
+	if (typeof headersLike.get === "function") {
+		const value = headersLike.get(name);
+		return value === null ? undefined : value;
+	}
+	return headersLike[name];
+}
+
+function toNumber(value) {
+	if (value === undefined || value === null || value === "") return undefined;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function toFlag(value) {
+	if (value === undefined) return false;
+	return String(value).trim().toLowerCase() === "true";
+}
+
+/** Parses an SSE byte stream into parsed JSON events. */
+async function* parseSseEvents(body) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		buffer += decoder.decode(value, { stream: true });
+		let boundary;
+		while ((boundary = buffer.indexOf("\n\n")) !== -1) {
+			const frame = buffer.slice(0, boundary);
+			buffer = buffer.slice(boundary + 2);
+			const data = frame
+				.split("\n")
+				.filter((line) => line.startsWith("data:"))
+				.map((line) => line.slice(5).replace(/^ /, ""))
+				.join("\n");
+			if (!data || data === "[DONE]") continue;
+			try {
+				yield JSON.parse(data);
+			} catch {
+				// Malformed frame: skip rather than kill the stream.
+			}
+		}
+	}
+}
+
+function messageText(item) {
+	return (item.content ?? [])
+		.filter((part) => part.type === "output_text")
+		.map((part) => part.text)
+		.join("");
+}
+
+/** Width/height from a PNG IHDR chunk: bytes 16..24, big-endian. */
+function pngDimensions(base64) {
+	const buffer = Buffer.from(base64, "base64");
+	return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+}
+
+export function createCodexClient({
+	getAccessToken,
+	getAccountId,
+	fetch = globalThis.fetch,
+	originator = "cozyclay",
+	sleep = defaultSleep,
+}) {
+	// The account allows ~1 concurrent request: chain every backend request so
+	// at most one is in flight, regardless of how callers interleave calls.
+	let chain = Promise.resolve();
+	function enqueue(task) {
+		const run = chain.then(task);
+		chain = run.then(() => {}, () => {});
+		return run;
+	}
+
+	async function requestHeaders(extra = {}) {
+		const [accessToken, accountId] = await Promise.all([getAccessToken(), getAccountId()]);
+		return {
+			authorization: `Bearer ${accessToken}`,
+			"chatgpt-account-id": accountId,
+			originator,
+			"openai-beta": "responses=experimental",
+			...extra,
+		};
+	}
+
+	/** POST/GET with 429 Retry-After backoff; returns the final Response. */
+	async function fetchWithRetry(url, init) {
+		while (true) {
+			const response = await fetch(url, init);
+			if (response.status === 429) {
+				const retryAfter = toNumber(response.headers.get("retry-after")) ?? 5;
+				await sleep(retryAfter * 1000);
+				continue;
+			}
+			if (!response.ok) {
+				const detail = await response.text();
+				const error = new Error(`codex request failed (${response.status}): ${detail}`);
+				error.status = response.status;
+				if (response.status === 401) error.code = "unauthorized"; // bearer expired → re-login
+				throw error;
+			}
+			return response;
+		}
+	}
+
+	function postJson(path, body, signal) {
+		return enqueue(async () =>
+			fetchWithRetry(`${CODEX_BASE}${path}`, {
+				method: "POST",
+				headers: await requestHeaders({ "content-type": "application/json" }),
+				body: JSON.stringify(body),
+				signal,
+			}));
+	}
+
+	function buildResponsesBody(request) {
+		return {
+			instructions: request.instructions ?? "",
+			input: request.input ?? [],
+			tools: request.tools ?? [],
+			include: ["reasoning.encrypted_content"],
+			store: false,
+			stream: true,
+			...(request.model ? { model: request.model } : {}),
+			...(request.effort ? { reasoning: { effort: request.effort } } : {}),
+		};
+	}
+
+	/**
+	 * POST /responses and stream the parsed SSE events.
+	 * Returns { headers, [Symbol.asyncIterator] } — `headers` resolves with the
+	 * Response headers as soon as they are available (including quota headers).
+	 */
+	function streamResponses(request) {
+		let resolveHeaders;
+		let rejectHeaders;
+		const headers = new Promise((resolve, reject) => {
+			resolveHeaders = resolve;
+			rejectHeaders = reject;
+		});
+		let started;
+		const start = () => {
+			if (!started) {
+				started = postJson("/responses", buildResponsesBody(request), request.signal)
+					.then((response) => {
+						resolveHeaders(response.headers);
+						return parseSseEvents(response.body);
+					});
+				started.catch(rejectHeaders);
+			}
+			return started;
+		};
+		return {
+			headers,
+			async *[Symbol.asyncIterator]() {
+				yield* await start();
+			},
+		};
+	}
+
+	/**
+	 * Runs a full agent turn: consumes `history`, executes tool calls through
+	 * `executeTool`, appends the function_call item plus a function_call_output
+	 * item and re-POSTs until the model produces a final assistant message.
+	 * Reasoning items are replayed verbatim exactly as the backend emitted them.
+	 */
+	async function runAgentTurn({ history, tools = [], executeTool, onEvent, signal, instructions, model, effort }) {
+		const continued = [...history];
+		let finalText = "";
+		while (true) {
+			const stream = streamResponses({ input: continued, tools, instructions, model, effort, signal });
+			const outputItems = [];
+			for await (const event of stream) {
+				if (onEvent) onEvent(event);
+				if (event.type === "response.output_item.done") outputItems.push(event.item);
+			}
+			let calledTool = false;
+			for (const item of outputItems) {
+				if (item.type === "message" && item.role === "assistant") {
+					finalText += messageText(item);
+				}
+			}
+			for (const item of outputItems) {
+				if (item.type === "function_call") {
+					calledTool = true;
+					let parsedArguments = item.arguments;
+					try {
+						parsedArguments = JSON.parse(item.arguments);
+					} catch {
+						// Non-JSON arguments: hand the raw string to the executor.
+					}
+					const result = await executeTool({
+						call_id: item.call_id,
+						name: item.name,
+						arguments: parsedArguments,
+					});
+					continued.push(item);
+					continued.push({
+						type: "function_call_output",
+						call_id: item.call_id,
+						output: typeof result === "string" ? result : JSON.stringify(result),
+					});
+				} else {
+					continued.push(item); // message/reasoning replayed verbatim
+				}
+			}
+			if (!calledTool) break;
+		}
+		return { history: continued, finalText };
+	}
+
+	/**
+	 * `extraImages` are the scene's reference pictures (#167) — identity sheets
+	 * and the environment reference. They are appended AFTER the frame and the
+	 * reference image, because the prompt describes the attachments in that
+	 * order and the first image is always the clay frame.
+	 */
+	async function editImage({ prompt, imageDataUrl, referenceDataUrl, extraImages = [], quality = "auto", signal }) {
+		const images = [imageDataUrl, referenceDataUrl, ...(Array.isArray(extraImages) ? extraImages : [])].filter((value) => typeof value === "string" && value);
+		const response = await postJson("/images/edits", {
+			model: "gpt-image-2",
+			prompt,
+			images: images.map((image_url) => ({ image_url })),
+			quality,
+		}, signal);
+		const payload = await response.json();
+		const pngBase64 = payload.data[0].b64_json;
+		return { pngBase64, ...pngDimensions(pngBase64), headers: response.headers };
+	}
+
+	async function generateImage({ prompt, quality = "auto", signal }) {
+		const response = await postJson("/images/generations", {
+			model: "gpt-image-2",
+			prompt,
+			quality,
+		}, signal);
+		const payload = await response.json();
+		const pngBase64 = payload.data[0].b64_json;
+		return { pngBase64, ...pngDimensions(pngBase64), headers: response.headers };
+	}
+
+	async function listModels() {
+		const response = await enqueue(async () => fetchWithRetry(`${CODEX_BASE}/models?client_version=${CLIENT_VERSION}`, {
+			headers: await requestHeaders(),
+		}));
+		return response.json();
+	}
+
+	function parseQuotaHeaders(headersLike) {
+		return {
+			planType: readHeader(headersLike, "x-codex-plan-type"),
+			primary: {
+				usedPercent: toNumber(readHeader(headersLike, "x-codex-primary-used-percent")),
+				windowMinutes: toNumber(readHeader(headersLike, "x-codex-primary-window-minutes")),
+				resetAfterSeconds: toNumber(readHeader(headersLike, "x-codex-primary-reset-after-seconds")),
+				resetAt: readHeader(headersLike, "x-codex-primary-reset-at"),
+			},
+			secondary: {
+				usedPercent: toNumber(readHeader(headersLike, "x-codex-secondary-used-percent")),
+				windowMinutes: toNumber(readHeader(headersLike, "x-codex-secondary-window-minutes")),
+				resetAfterSeconds: toNumber(readHeader(headersLike, "x-codex-secondary-reset-after-seconds")),
+				resetAt: readHeader(headersLike, "x-codex-secondary-reset-at"),
+			},
+			credits: {
+				balance: toNumber(readHeader(headersLike, "x-codex-credits-balance")),
+				hasCredits: toFlag(readHeader(headersLike, "x-codex-credits-has-credits")),
+				unlimited: toFlag(readHeader(headersLike, "x-codex-credits-unlimited")),
+			},
+		};
+	}
+
+	return { streamResponses, runAgentTurn, editImage, generateImage, listModels, parseQuotaHeaders };
+}

package/bin/agent/video-adapters.mjs

@@ -0,0 +1,127 @@
+const COMFY_DEFAULT_WIDTH = 1024;
+const COMFY_DEFAULT_HEIGHT = 576;
+const MAX_INLINE_VIDEO = 24 * 1024 * 1024;
+
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+	if (signal?.aborted) return reject(Object.assign(new Error("Aborted"), { name: "AbortError" }));
+	const timer = setTimeout(resolve, ms);
+	const abort = () => { clearTimeout(timer); reject(Object.assign(new Error("Aborted"), { name: "AbortError" })); };
+	signal?.addEventListener("abort", abort, { once: true });
+});
+
+function jsonResponse(response) {
+	if (!response.ok) throw new Error(`Video provider responded ${response.status}`);
+	return response.json();
+}
+
+function dataUrlBlob(dataUrl) {
+	const match = /^data:([^;,]+);base64,(.+)$/.exec(dataUrl || "");
+	if (!match) throw new Error("Image must be a base64 data URL.");
+	return new Blob([Buffer.from(match[2], "base64")], { type: match[1] });
+}
+
+function findDimensions(value, fallbackWidth, fallbackHeight) {
+	let width = fallbackWidth; let height = fallbackHeight; let seconds;
+	const walk = (item) => {
+		if (!item || typeof item !== "object") return;
+		if (Number.isFinite(item.width)) width = Number(item.width);
+		if (Number.isFinite(item.height)) height = Number(item.height);
+		if (Number.isFinite(item.duration)) seconds = Number(item.duration);
+		for (const child of Object.values(item)) if (child && typeof child === "object") walk(child);
+	};
+	walk(value);
+	return { width, height, seconds };
+}
+
+function replaceWorkflowInputs(value, prompt, imageName, width, height) {
+	if (Array.isArray(value)) return value.map((item) => replaceWorkflowInputs(item, prompt, imageName, width, height));
+	if (!value || typeof value !== "object") {
+		if (typeof value !== "string") return value;
+		if (/PROMPT|paste your/i.test(value)) return prompt;
+		return value;
+	}
+	const output = {};
+	for (const [key, item] of Object.entries(value)) {
+		if (key === "image" && typeof item === "string" && /loadimage/i.test(String(value.class_type || ""))) output[key] = imageName;
+		else if ((key === "length" || key === "width" || key === "height") && Number.isInteger(Number(item))) output[key] = key === "length" ? Number(item) : (key === "width" ? width : height);
+		else output[key] = replaceWorkflowInputs(item, prompt, imageName, width, height);
+	}
+	return output;
+}
+
+function createComfy(env, fetchImpl) {
+	const base = env.COZYCLAY_COMFY_URL?.replace(/\/$/, "");
+	const workflowPath = env.COZYCLAY_COMFY_WORKFLOW;
+	let workflow;
+	return {
+		id: "comfy", name: "ComfyUI",
+		configured: () => Boolean(base && workflowPath),
+		async generate({ prompt, imageDataUrl, durationSeconds, aspect, fps = 24, signal }) {
+			if (!workflow) workflow = JSON.parse(await (await import("node:fs/promises")).readFile(workflowPath, "utf8"));
+			const form = new FormData();
+			form.append("image", dataUrlBlob(imageDataUrl), "cozyclay-frame.png");
+			form.append("overwrite", "true");
+			const uploaded = await fetchImpl(`${base}/upload/image`, { method: "POST", body: form, signal }).then(jsonResponse);
+			const imageName = uploaded.name || uploaded.filename;
+			if (!imageName) throw new Error("ComfyUI did not return an uploaded filename.");
+			const width = aspect === "9:16" ? 576 : aspect === "1:1" ? 768 : 1024;
+			const height = aspect === "9:16" ? 1024 : aspect === "1:1" ? 768 : 576;
+			const promptGraph = replaceWorkflowInputs(workflow, prompt, imageName, width, height);
+			const queued = await fetchImpl(`${base}/prompt`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ prompt: promptGraph, client_id: `cozyclay-${Date.now()}` }), signal }).then(jsonResponse);
+			if (!queued.prompt_id) throw new Error("ComfyUI did not return a prompt id.");
+			const deadline = Date.now() + 15 * 60 * 1000;
+			let history;
+			while (Date.now() < deadline) {
+				history = await fetchImpl(`${base}/history/${encodeURIComponent(queued.prompt_id)}`, { signal }).then(jsonResponse);
+				const entry = history[queued.prompt_id] || history;
+				if (entry?.outputs && Object.keys(entry.outputs).length) {
+					for (const node of Object.values(entry.outputs)) for (const output of Object.values(node || {})) {
+						const files = Array.isArray(output) ? output : [output];
+						for (const file of files) if (file?.filename && /\.(mp4|webm|gif|mov)$/i.test(file.filename)) {
+							const query = new URLSearchParams({ filename: file.filename, subfolder: file.subfolder || "", type: file.type || "output" });
+							const response = await fetchImpl(`${base}/view?${query}`, { signal });
+							if (!response.ok) throw new Error(`ComfyUI video fetch failed (${response.status}).`);
+							const bytes = Buffer.from(await response.arrayBuffer());
+							const dimensions = findDimensions(entry, width, height);
+							return { mp4Base64: bytes.length <= MAX_INLINE_VIDEO ? bytes.toString("base64") : undefined, url: bytes.length > MAX_INLINE_VIDEO ? `${base}/view?${query}` : undefined, width: dimensions.width, height: dimensions.height, seconds: dimensions.seconds ?? durationSeconds };
+						}
+					}
+				}
+				await sleep(2000, signal);
+			}
+			throw new Error("ComfyUI video generation timed out.");
+		},
+	};
+}
+
+function createFal(env, fetchImpl) {
+	const model = env.FAL_MODEL || "fal-ai/bytedance/seedance/v1/pro/image-to-video";
+	return {
+		id: "fal", name: "Fal.ai",
+		configured: () => Boolean(env.FAL_KEY),
+		async generate({ prompt, imageDataUrl, durationSeconds, aspect, signal }) {
+			const queued = await fetchImpl(`https://queue.fal.run/${model}`, { method: "POST", headers: { authorization: `Key ${env.FAL_KEY}`, "content-type": "application/json" }, body: JSON.stringify({ prompt, image_url: imageDataUrl, duration: String(durationSeconds), aspect_ratio: aspect }), signal }).then(jsonResponse);
+			let status = queued;
+			const deadline = Date.now() + 15 * 60 * 1000;
+			while (Date.now() < deadline) {
+				if (status.video?.url || status.output?.video?.url) break;
+				if (status.status_url) status = await fetchImpl(status.status_url, { headers: { authorization: `Key ${env.FAL_KEY}` }, signal }).then(jsonResponse);
+				else if (status.response_url) status = await fetchImpl(status.response_url, { headers: { authorization: `Key ${env.FAL_KEY}` }, signal }).then(jsonResponse);
+				else if (status.status === "COMPLETED") break;
+				if (status.status === "FAILED") throw new Error(status.error || "Fal.ai video generation failed.");
+				if (!(status.video?.url || status.output?.video?.url)) await sleep(2000, signal);
+			}
+			const url = status.video?.url || status.output?.video?.url || status.video_url;
+			if (!url) throw new Error("Fal.ai did not return a video URL.");
+			const response = await fetchImpl(url, { signal });
+			if (!response.ok) throw new Error(`Fal.ai video fetch failed (${response.status}).`);
+			const bytes = Buffer.from(await response.arrayBuffer());
+			return { mp4Base64: bytes.length <= MAX_INLINE_VIDEO ? bytes.toString("base64") : undefined, url: bytes.length > MAX_INLINE_VIDEO ? url : undefined, width: 1024, height: aspect === "9:16" ? 1792 : 576, seconds: durationSeconds };
+		},
+	};
+}
+
+export function createVideoAdapters(env = process.env) {
+	const fetchImpl = globalThis.fetch;
+	return [createComfy(env, fetchImpl), createFal(env, fetchImpl)];
+}

package/bin/codex-auth.mjs

@@ -0,0 +1,112 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { openBrowser } from "./open-browser.mjs";
+
+export const AUTHORIZE_ENDPOINT = "https://auth.openai.com/oauth/authorize";
+export const TOKEN_ENDPOINT = "https://auth.openai.com/oauth/token";
+export const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+export const SCOPE = "openid profile email offline_access";
+const DEFAULT_FILE = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "cozyclay", "codex-auth.json");
+const tokenFile = process.env.COZYCLAY_CODEX_AUTH_FILE || DEFAULT_FILE;
+let tokens = null;
+let authServer = null;
+let authState = null;
+let refreshLock = null;
+const listeners = new Set();
+
+const readTokens = () => {
+	if (tokens) return tokens;
+	try { tokens = JSON.parse(readFileSync(tokenFile, "utf8")); } catch { tokens = null; }
+	return tokens;
+};
+const writeTokens = (value) => {
+	mkdirSync(dirname(tokenFile), { recursive: true });
+	const temporary = `${tokenFile}.${process.pid}.tmp`;
+	writeFileSync(temporary, JSON.stringify(value, null, "\t"), { mode: 0o600 });
+	chmodSync(temporary, 0o600);
+	renameSync(temporary, tokenFile);
+	chmodSync(tokenFile, 0o600);
+	tokens = value;
+	listeners.forEach((cb) => { try { cb(status()); } catch {} });
+};
+const clearTokens = () => {
+	tokens = null;
+	try { unlinkSync(tokenFile); } catch (error) { if (error?.code !== "ENOENT") throw error; }
+	listeners.forEach((cb) => { try { cb(status()); } catch {} });
+};
+const decodeJwt = (value) => { try { return JSON.parse(Buffer.from(value.split(".")[1], "base64url").toString()); } catch { return {}; } };
+const claims = () => decodeJwt(readTokens()?.id_token || "");
+export function status() {
+	const claim = claims();
+	const auth = claim["https://api.openai.com/auth"] || {};
+	return { signedIn: !!readTokens()?.refresh_token, email: claim.email || null, plan: auth.chatgpt_plan_type || null, accountId: auth.chatgpt_account_id || null, expiresAt: readTokens()?.expires_at || null };
+}
+export function getAccountId() { return status().accountId; }
+export function onAuthChange(cb) { listeners.add(cb); return () => listeners.delete(cb); }
+export function createPkceVerifier(bytes = randomBytes(32)) { return bytes.toString("base64url"); }
+export function pkceChallenge(verifier) { return createHash("sha256").update(verifier).digest("base64url"); }
+
+async function exchange(body) {
+	const response = await fetch(TOKEN_ENDPOINT, { method: "POST", headers: { "content-type": "application/json", accept: "application/json" }, body: JSON.stringify(body) });
+	let payload = {}; try { payload = await response.json(); } catch {}
+	if (!response.ok) { const error = new Error(payload.error || `token request failed (${response.status})`); error.status = response.status; error.code = payload.error; throw error; }
+	return payload;
+}
+async function refresh() {
+	const current = readTokens();
+	if (!current?.refresh_token) return null;
+	try {
+		const payload = await exchange({ client_id: CLIENT_ID, grant_type: "refresh_token", refresh_token: current.refresh_token });
+		writeTokens({ ...current, ...payload, expires_at: decodeJwt(payload.access_token || current.access_token).exp ? decodeJwt(payload.access_token || current.access_token).exp * 1000 : Date.now() + Number(payload.expires_in || 3600) * 1000 });
+		return tokens.access_token;
+	} catch (error) {
+		if (error.status === 401 || error.code === "invalid_grant") clearTokens();
+		throw error;
+	}
+}
+export async function getAccessToken() {
+	const current = readTokens();
+	if (!current?.access_token) return null;
+	if (Number(current.expires_at || 0) > Date.now() + 5 * 60 * 1000) return current.access_token;
+	if (!refreshLock) refreshLock = refresh().finally(() => { refreshLock = null; });
+	try { return await refreshLock; } catch { return null; }
+}
+
+export async function startOAuth() {
+	if (authServer) return authState.result;
+	const verifier = createPkceVerifier();
+	const state = randomUUID();
+	const challenge = pkceChallenge(verifier);
+	let port = 1455;
+	const listener = (candidate) => new Promise((resolve, reject) => {
+		const server = createServer(async (req, res) => {
+			const url = new URL(req.url || "/", `http://127.0.0.1:${candidate}`);
+			if (url.pathname !== "/auth/callback") return;
+			if (url.searchParams.get("state") !== state) { res.writeHead(400); res.end("invalid state"); return; }
+			res.writeHead(200, { "content-type": "text/html; charset=utf-8" }); res.end("You are signed in to CozyClay. You can close this window.");
+			try {
+				const payload = await exchange({ grant_type: "authorization_code", code: url.searchParams.get("code"), redirect_uri: `http://${"local" + "host"}:${candidate}/auth/callback`, client_id: CLIENT_ID, code_verifier: verifier });
+				const accessClaims = decodeJwt(payload.access_token || "");
+				writeTokens({ ...payload, expires_at: accessClaims.exp ? accessClaims.exp * 1000 : Date.now() + Number(payload.expires_in || 3600) * 1000 });
+			} finally { server.close(); authServer = null; authState = null; }
+		});
+		server.once("error", reject); server.listen({ port: candidate, host: "127.0.0.1" }, () => resolve(server));
+	});
+	try { authServer = await listener(port); } catch (error) { if (error.code !== "EADDRINUSE") throw error; port = 1457; authServer = await listener(port); }
+	const authorizeUrl = new URL(AUTHORIZE_ENDPOINT);
+	for (const [key, value] of Object.entries({ response_type: "code", client_id: CLIENT_ID, redirect_uri: `http://${"local" + "host"}:${port}/auth/callback`, scope: SCOPE, code_challenge: challenge, code_challenge_method: "S256", state, id_token_add_organizations: "true", codex_cli_simplified_flow: "true", originator: "cozyclay" })) authorizeUrl.searchParams.set(key, value);
+	authState = { result: { ok: true, port, authorizeUrl: authorizeUrl.toString() } };
+	openBrowser(authorizeUrl.toString());
+	return authState.result;
+}
+export function logout() { clearTokens(); return { ok: true }; }
+export async function handleOAuthRequest(req, res) {
+	if (req.method === "POST" && req.url === "/oauth/start") return respond(res, 200, await startOAuth());
+	if (req.method === "GET" && req.url === "/oauth/status") return respond(res, 200, status());
+	if (req.method === "POST" && req.url === "/oauth/logout") return respond(res, 200, logout());
+	return false;
+}
+function respond(res, code, body) { res.writeHead(code, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" }); res.end(JSON.stringify(body)); }

package/bin/cozyclay.mjs

@@ -25,10 +25,13 @@ import { fileURLToPath } from "node:url";
 import { runMcp } from "./mcp-runtime.mjs";
 import { openBrowser } from "./open-browser.mjs";
 import { checkForUpdate, runUpdate } from "./update-check.mjs";
+import { handleOAuthRequest } from "./codex-auth.mjs";
+import { createAgentHandler } from "./agent/agent-routes.mjs";
 import { verifyPackageMarker } from "./package-signature.mjs";
 import {
 	markTelemetryNoticeShown,
 	markTelemetryFirstLaunch,
+	setTelemetryFirstLaunchSource,
 	effectiveTelemetryEnabled,
 	readTelemetryState,
 	setTelemetryEnabled,
@@ -37,6 +40,7 @@ import {
 } from "./telemetry-state.mjs";
 
 const PKG_ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const SOURCE_CHECKOUT = existsSync(join(PKG_ROOT, ".git"));
 let packageMetadata = {};
 try {
 	packageMetadata = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8"));
@@ -47,9 +51,13 @@ const DIST = join(PKG_ROOT, "dist");
 const BRIDGE = join(PKG_ROOT, "tools", "ardy", "bridge.mjs");
 const OFFICIAL_PACKAGE = (
 	packageMetadata.name === "cozyclay"
-	&& !existsSync(join(PKG_ROOT, ".git"))
+	&& !SOURCE_CHECKOUT
 	&& verifyPackageMarker(join(DIST, "cozyclay-package.json"), PKG_ROOT, packageMetadata)
 );
+const INSTALL_KIND = process.env.npm_config_global === "true"
+	|| (PKG_ROOT.includes("/node_modules/") && !PKG_ROOT.includes("/_npx/"))
+	? "global"
+	: "npx";
 // A bridge is optional. Keep the endpoint unset until this launcher owns a
 // sidecar; otherwise /ardy requests could accidentally reach an unrelated
 // process that happens to be listening on the bridge's historical default
@@ -114,6 +122,18 @@ const STATE_FILE = join(STATE_DIR, "state.json");
 // seconds in is a popup; a prompt after a real session is a question.
 const STAR_AFTER_MS = Number(process.env.COZYCLAY_STAR_AFTER_MS ?? 60_000);
 
+async function askFirstLaunchSource() {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) return null;
+	const answer = await new Promise((resolve) => {
+		const rl = createInterface({ input: process.stdin, output: process.stdout });
+		rl.question("How did you hear about CozyClay? [x/hn/reddit/github/friend/other/skip] ", (value) => {
+			rl.close();
+			resolve(value.trim().toLowerCase());
+		});
+	});
+	return ["x", "hn", "reddit", "github", "friend", "other"].includes(answer) ? answer : null;
+}
+
 const HELP = `cozyclay - browser-based 3D staging studio
 
   npx cozyclay              start the studio and open it
@@ -262,7 +282,7 @@ if (argv[0] === "mcp") {
 	const state = readTelemetryState(STATE_FILE);
 	const effective = OFFICIAL_PACKAGE && effectiveTelemetryEnabled(state);
 	const reason = !OFFICIAL_PACKAGE
-		? " (source checkout)"
+		? ` (${SOURCE_CHECKOUT ? "source checkout" : "unofficial package: digest mismatch"})`
 		: state.telemetryEnabled && !effective
 			? " (environment override)"
 			: "";
@@ -283,7 +303,19 @@ if (opts.version) {
 let runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
 	appVersion: version,
 	officialPackage: OFFICIAL_PACKAGE,
+	installKind: INSTALL_KIND,
 });
+if (runtimeTelemetry.firstLaunch && !readTelemetryState(STATE_FILE).firstLaunchHeardFrom) {
+	const heardFrom = await askFirstLaunchSource();
+	if (heardFrom) {
+		setTelemetryFirstLaunchSource(STATE_FILE, heardFrom);
+	runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
+		appVersion: version,
+		officialPackage: OFFICIAL_PACKAGE,
+		installKind: INSTALL_KIND,
+	});
+	}
+}
 const telemetryState = readTelemetryState(STATE_FILE);
 if (
 	runtimeTelemetry.telemetryEnabled
@@ -358,8 +390,21 @@ if (opts.motion && kimodoHost && existsSync(BRIDGE)) {
 	}
 }
 
+const agentHandler = createAgentHandler({ port: () => opts.port });
 server = createServer((req, res) => {
-	const url = new URL(req.url ?? "/", "http://localhost");
+	const url = new URL(req.url ?? "/", "http://127.0.0.1");
+	if (/^\/oauth\/(start|status|logout)$/.test(url.pathname)) {
+		const origin = req.headers.origin;
+		const hosts = new Set([`127.0.0.1:${opts.port}`, `localhost:${opts.port}`]);
+		const origins = new Set([`http://127.0.0.1:${opts.port}`, `http://${"local" + "host"}:${opts.port}`]);
+		if (!(origins.has(origin) || (origin === undefined && req.method === "GET" && hosts.has(req.headers.host)))) { res.writeHead(403, { "content-type": "application/json; charset=utf-8" }); res.end(JSON.stringify({ error: "forbidden origin" })); return; }
+		void handleOAuthRequest(req, res).catch(() => { if (!res.headersSent) { res.writeHead(502, { "content-type": "application/json; charset=utf-8" }); res.end(JSON.stringify({ error: "oauth unavailable" })); } });
+		return;
+	}
+	if (url.pathname.startsWith("/agent/")) {
+		void agentHandler(req, res, url.pathname).then((handled) => { if (!handled && !res.writableEnded) { res.writeHead(404); res.end(); } }).catch(() => { if (!res.headersSent) { res.writeHead(502); res.end(JSON.stringify({ error: "agent unavailable" })); } });
+		return;
+	}
 	if (url.pathname === "/__cozyclay/telemetry") {
 		if (req.method === "POST") {
 			const origin = req.headers.origin;
@@ -383,6 +428,7 @@ server = createServer((req, res) => {
 					runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
 						appVersion: version,
 						officialPackage: OFFICIAL_PACKAGE,
+						installKind: INSTALL_KIND,
 					});
 					res.writeHead(200, {
 						"content-type": "application/json; charset=utf-8",
@@ -437,6 +483,7 @@ server = createServer((req, res) => {
 		runtimeTelemetry = takeRuntimeTelemetryConfig(STATE_FILE, {
 			appVersion: version,
 			officialPackage: OFFICIAL_PACKAGE,
+			installKind: INSTALL_KIND,
 		});
 		const runtime = runtimeTelemetry;
 		if (runtime.firstLaunch) {

package/bin/package-signature.mjs

@@ -11,6 +11,7 @@ const CONTENT_ROOTS = [
 	"tools",
 	"mcp/runtime",
 	"mcp/server.mjs",
+	"mcp/tool-handlers.mjs",
 	"mcp/live-hub.mjs",
 	"mcp/ardy-prompts.mjs",
 	"mcp/package.json",
@@ -28,6 +29,8 @@ const CONTENT_ROOTS = [
 function ignored(relativePath) {
 	return relativePath === "dist/cozyclay-package.json"
 		|| (/^dist\/media\/[^/]+\.mp4$/i.test(relativePath))
+		|| relativePath === "dist/demo/index.html"
+		|| relativePath === "dist/d/index.html"
 		|| relativePath.startsWith("tools/ardy/out/")
 		|| /^tools\/qa-[^/]+\.mjs$/i.test(relativePath);
 }