@neta-art/cohub 5.2.0 → 5.3.1

package/dist/index.js

@@ -1,5 +1,5 @@
-import { A as CronJobsApi, C as ReferencesApi, D as PromptsApi, E as SkillsApi, O as ModelsApi, S as SessionAccessApi, T as PublicAssetsApi, _ as createSessionGenerationStreamClient, a as ReferralsApi, b as createSessionPatchReducer, c as TasksApi, d as SpaceClient, f as SpacesApi, g as SessionGenerationStreamClient, h as buildSpacePath, i as WorksApi, j as ChannelsApi, k as GenerationsApi, l as BoardClient, m as buildSpaceInvitePath, n as createHttpClient, o as UsersApi, p as PublicInviteApi, r as WorkCommerceApi, s as UserApi, t as CohubHttpClient, u as BoardTransactionError, v as parseAssistantMessageCommit, w as SearchApi, x as ensureRealtimeConnected, y as SessionPatchReducer } from "./chunks/http.js";
-import { _ as resolveRequestSourceChannel, a as sanitizeAccessToken, c as REQUEST_SOURCE_VIA_MAX_LENGTH, d as isRequestSourceUuid, f as mergeRequestSourceIntoMeta, g as requestSourceToHeaders, h as readRequestSourceFromEnv, i as matchesUnauthorizedErrorToken, l as hasRequestSourceIdentity, m as parseRequestSourceFromHeaders, n as HttpTransport, o as COHUB_SOURCE_HEADER, p as normalizeRequestSource, r as joinApiUrl, s as COHUB_SOURCE_HEADER_NAMES, t as HttpError, u as isRequestSourceEmpty, v as REALTIME_ROOM_EVENT_NAME_PATTERN } from "./chunks/transport.js";
+import { A as parseAssistantMessageCommit, B as ModelsApi, C as SpaceClient, D as buildSpacePath, E as buildSpaceInvitePath, F as ReferencesApi, H as CronJobsApi, I as SearchApi, L as PublicAssetsApi, M as createSessionPatchReducer, N as ensureRealtimeConnected, O as SessionGenerationStreamClient, P as SessionAccessApi, R as SkillsApi, S as BoardTransactionError, T as PublicInviteApi, U as ChannelsApi, V as GenerationsApi, _ as isUiSurfaceMethod, a as ReferralsApi, b as TasksApi, c as UiCommandsApi, d as UI_COMMAND_PAYLOAD_MAX_BYTES, f as UI_COMMAND_PENDING_TTL_SECONDS, g as isTerminalUiCommandStatus, h as UI_COMMAND_VERSION, i as WorksApi, j as SessionPatchReducer, k as createSessionGenerationStreamClient, l as UI_COMMAND_DEFAULT_TIMEOUT_MS, m as UI_COMMAND_TERMINAL_TTL_SECONDS, n as createHttpClient, o as UsersApi, p as UI_COMMAND_SETTLEMENT_GRACE_SECONDS, r as WorkCommerceApi, s as UserApi, t as CohubHttpClient, u as UI_COMMAND_MAX_TIMEOUT_MS, v as parseUiCommand, w as SpacesApi, x as BoardClient, y as parseUiCommandId, z as PromptsApi } from "./chunks/http.js";
+import { _ as requestSourceToHeaders, a as sanitizeAccessToken, c as REQUEST_SOURCE_VIA_MAX_LENGTH, d as isRequestSourceEmpty, f as isRequestSourceUuid, g as readRequestSourceFromEnv, h as parseRequestSourceFromHeaders, i as matchesUnauthorizedErrorToken, l as hasRequestSourceIdentity, m as normalizeRequestSource, n as HttpTransport, o as COHUB_SOURCE_HEADER, p as mergeRequestSourceIntoMeta, r as joinApiUrl, s as COHUB_SOURCE_HEADER_NAMES, t as HttpError, u as isRequestSourceClientId, v as resolveRequestSourceChannel, y as REALTIME_ROOM_EVENT_NAME_PATTERN } from "./chunks/transport.js";
 import { a as resolveApiBaseUrl, c as resolveWebsocketUrl, i as normalizeWebsocketUrl, n as normalizeBaseUrl, o as resolveCohubEnvironment, r as normalizeVoiceInputWebsocketUrl, s as resolveVoiceInputWebsocketUrl, t as COHUB_ENVIRONMENTS } from "./chunks/environment.js";
 import { a as extractBillingPayload, c as isFeatureNotEntitledError, i as FEATURE_NOT_ENTITLED_ERROR_CODE, l as isHttpErrorCode, n as createWebsocketClient, o as isBillingAccessBlockedCode, r as BILLING_ACCESS_BLOCKED_ERROR_CODE, s as isBillingAccessBlockedError, t as WebsocketClient } from "./chunks/websocket.js";
 import { VoiceApi, VoiceInputClient, createVoiceInputClient } from "./voice-input.js";
@@ -389,7 +389,8 @@ z.object({
 		"session",
 		"space",
 		"label",
-		"room"
+		"room",
+		"ui"
 	]),
 	type: z.string(),
 	requestId: z.string().nullable().optional(),
@@ -843,6 +844,257 @@ var WorkRealtimeApi = class {
 	}
 };
 //#endregion
+//#region ../protocol/dist/work-surface.js
+const WORK_SURFACE_PROTOCOL = "cohub.surface";
+const WORK_SURFACE_READY_TIMEOUT_MS = 1e4;
+const WORK_SURFACE_REQUEST_TIMEOUT_MS = 15e3;
+const WORK_COMPOSER_CHIP_KEY_MAX_LENGTH = 80;
+const WORK_COMPOSER_CHIP_LABEL_MAX_LENGTH = 120;
+const WORK_COMPOSER_CHIP_CONTENT_MAX_BYTES = 32 * 1024;
+const isRecord$1 = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const isSurfaceEnvelope = (value) => isRecord$1(value) && value.protocol === "cohub.surface" && value.version === 1;
+const parseWorkSurfaceReady = (value) => {
+	if (!isSurfaceEnvelope(value) || value.type !== "ready") return null;
+	const methods = Array.isArray(value.methods) ? value.methods.filter((method) => typeof method === "string" && Boolean(method)) : [];
+	return {
+		protocol: WORK_SURFACE_PROTOCOL,
+		version: 1,
+		type: "ready",
+		methods
+	};
+};
+const parseWorkSurfaceResponse = (value) => {
+	if (!isSurfaceEnvelope(value) || value.type !== "response") return null;
+	if (typeof value.requestId !== "string" || !value.requestId) return null;
+	const error = isRecord$1(value.error) ? {
+		code: typeof value.error.code === "string" && value.error.code ? value.error.code : "surface_error",
+		message: typeof value.error.message === "string" ? value.error.message : "Work surface call failed"
+	} : void 0;
+	return {
+		protocol: WORK_SURFACE_PROTOCOL,
+		version: 1,
+		type: "response",
+		requestId: value.requestId,
+		ok: value.ok === true,
+		...error ? { error } : {}
+	};
+};
+const parseComposerChipKey = (value) => {
+	if (typeof value !== "string") return null;
+	const key = value.trim();
+	if (!key || key.length > 80) return null;
+	return key;
+};
+const parseWorkComposerChipSet = (value) => {
+	if (!isSurfaceEnvelope(value) || value.type !== "composer.chip.set" || !isRecord$1(value.chip)) return null;
+	const key = parseComposerChipKey(value.chip.key);
+	if (!key || typeof value.chip.label !== "string" || typeof value.chip.content !== "string") return null;
+	const label = value.chip.label.trim();
+	if (!label || label.length > 120) return null;
+	if (!value.chip.content.trim()) return null;
+	if (new TextEncoder().encode(value.chip.content).length > 32768) return null;
+	return {
+		protocol: WORK_SURFACE_PROTOCOL,
+		version: 1,
+		type: "composer.chip.set",
+		chip: {
+			key,
+			label,
+			content: value.chip.content
+		}
+	};
+};
+const parseWorkComposerChipClear = (value) => {
+	if (!isSurfaceEnvelope(value) || value.type !== "composer.chip.clear") return null;
+	const key = parseComposerChipKey(value.key);
+	return key ? {
+		protocol: WORK_SURFACE_PROTOCOL,
+		version: 1,
+		type: "composer.chip.clear",
+		key
+	} : null;
+};
+const parseWorkSurfaceRequest = (value) => {
+	if (!isSurfaceEnvelope(value) || value.type !== "request") return null;
+	if (typeof value.requestId !== "string" || !value.requestId) return null;
+	if (typeof value.method !== "string" || !value.method) return null;
+	const commandId = parseUiCommandId(value.commandId);
+	if (!commandId) return null;
+	return {
+		protocol: WORK_SURFACE_PROTOCOL,
+		version: 1,
+		type: "request",
+		requestId: value.requestId,
+		method: value.method,
+		...value.input === void 0 ? {} : { input: value.input },
+		commandId
+	};
+};
+const buildWorkSurfaceReady = (methods) => ({
+	protocol: WORK_SURFACE_PROTOCOL,
+	version: 1,
+	type: "ready",
+	methods: [...methods]
+});
+const buildWorkSurfaceRequest = (input) => ({
+	protocol: WORK_SURFACE_PROTOCOL,
+	version: 1,
+	type: "request",
+	...input
+});
+const buildWorkSurfaceResponse = (input) => ({
+	protocol: WORK_SURFACE_PROTOCOL,
+	version: 1,
+	type: "response",
+	...input
+});
+const buildWorkComposerChipSet = (chip) => ({
+	protocol: WORK_SURFACE_PROTOCOL,
+	version: 1,
+	type: "composer.chip.set",
+	chip
+});
+const buildWorkComposerChipClear = (key) => ({
+	protocol: WORK_SURFACE_PROTOCOL,
+	version: 1,
+	type: "composer.chip.clear",
+	key
+});
+//#endregion
+//#region src/work-surface.ts
+/**
+* Explicit app origins, not a `*.cohub.run` suffix match: Works themselves are
+* served from Cohub subdomains, so a suffix match would let one Work call into
+* another and turn a subdomain takeover into surface access.
+*/
+const COHUB_APP_ORIGINS = [
+	"https://cohub.run",
+	"https://www.cohub.run",
+	"https://dev.cohub.run"
+];
+const isCohubHostOrigin = (origin) => COHUB_APP_ORIGINS.includes(origin);
+const resolveEmbedderOrigin = () => {
+	if (typeof window === "undefined" || window.parent === window) return null;
+	const ancestor = window.location?.ancestorOrigins?.[0];
+	if (typeof ancestor === "string" && ancestor) return ancestor;
+	try {
+		const referrer = typeof document === "undefined" ? "" : document.referrer;
+		return referrer ? new URL(referrer).origin : null;
+	} catch {
+		return null;
+	}
+};
+var WorkSurfaceApi = class {
+	handlers = /* @__PURE__ */ new Map();
+	listening = false;
+	allowedOrigins = null;
+	trustedOrigin;
+	allowHostOrigins(origins) {
+		this.allowedOrigins = origins.map((origin) => origin.trim()).filter(Boolean).map((origin) => {
+			try {
+				return new URL(origin).origin;
+			} catch {
+				return "";
+			}
+		}).filter(Boolean);
+		this.trustedOrigin = void 0;
+		this.announce();
+	}
+	handle(method, handler) {
+		const name = method.trim();
+		if (!name) throw new Error("Work surface method name is required");
+		this.handlers.set(name, handler);
+		this.start();
+		this.announce();
+		return () => {
+			if (this.handlers.get(name) === handler) {
+				this.handlers.delete(name);
+				this.announce();
+			}
+		};
+	}
+	get methods() {
+		return [...this.handlers.keys()];
+	}
+	setComposerChip(chip) {
+		const message = parseWorkComposerChipSet(buildWorkComposerChipSet(chip));
+		if (!message) throw new Error("Invalid Work composer chip");
+		this.post(message);
+	}
+	clearComposerChip(key) {
+		const message = parseWorkComposerChipClear(buildWorkComposerChipClear(key));
+		if (!message) throw new Error("Invalid Work composer chip key");
+		this.post(message);
+	}
+	announce() {
+		this.post(buildWorkSurfaceReady(this.methods));
+	}
+	isTrusted(origin) {
+		if (!origin || origin === "null") return false;
+		if (typeof window !== "undefined" && origin === window.location?.origin) return true;
+		return this.allowedOrigins ? this.allowedOrigins.includes(origin) : isCohubHostOrigin(origin);
+	}
+	resolveTrustedOrigin() {
+		if (this.trustedOrigin !== void 0) return this.trustedOrigin;
+		const embedder = resolveEmbedderOrigin();
+		this.trustedOrigin = embedder && this.isTrusted(embedder) ? embedder : null;
+		return this.trustedOrigin;
+	}
+	start() {
+		if (this.listening || typeof window === "undefined") return;
+		this.listening = true;
+		window.addEventListener("message", this.onMessage);
+	}
+	onMessage = (event) => {
+		if (typeof window === "undefined" || event.source !== window.parent) return;
+		if (!this.isTrusted(event.origin)) return;
+		const request = parseWorkSurfaceRequest(event.data);
+		if (!request) return;
+		const commandId = request.commandId;
+		if (!commandId) return;
+		this.trustedOrigin = event.origin;
+		this.dispatch(request.requestId, request.method, request.input, commandId);
+	};
+	async dispatch(requestId, method, input, commandId) {
+		const handler = this.handlers.get(method);
+		if (!handler) {
+			this.post(buildWorkSurfaceResponse({
+				requestId,
+				ok: false,
+				error: {
+					code: "method_not_found",
+					message: `This Work does not expose "${method}".`
+				}
+			}));
+			return;
+		}
+		try {
+			await handler(input, { commandId });
+			this.post(buildWorkSurfaceResponse({
+				requestId,
+				ok: true
+			}));
+		} catch (error) {
+			this.post(buildWorkSurfaceResponse({
+				requestId,
+				ok: false,
+				error: {
+					code: "handler_failed",
+					message: error instanceof Error ? error.message : String(error)
+				}
+			}));
+		}
+	}
+	post(message) {
+		if (typeof window === "undefined" || window.parent === window) return;
+		const origin = this.resolveTrustedOrigin();
+		if (!origin) return;
+		try {
+			window.parent.postMessage(message, origin);
+		} catch {}
+	}
+};
+//#endregion
 //#region src/work-runtime.ts
 const isBrowser$1 = () => typeof window !== "undefined" && typeof window.parent !== "undefined";
 const hasParent = () => isBrowser$1() && window.parent !== window;
@@ -1240,6 +1492,7 @@ var CohubClient = class {
 	references;
 	tasks;
 	cronJobs;
+	ui;
 	invite;
 	referrals;
 	voice;
@@ -1296,6 +1549,7 @@ var CohubClient = class {
 		this.references = new ReferencesApi(this.transport);
 		this.tasks = new TasksApi(this.transport);
 		this.cronJobs = new CronJobsApi(this.transport);
+		this.ui = new UiCommandsApi(this.transport);
 		this.invite = new PublicInviteApi(this.transport);
 		this.referrals = new ReferralsApi(this.transport);
 		this.works = new WorksApi(this.transport);
@@ -1308,6 +1562,14 @@ var CohubClient = class {
 	auth = { request: (input) => this.workRuntime.requestAuthorization(input) };
 	work = {
 		realtime: null,
+		/** Expose callable methods from inside a published Work. */
+		surface: new WorkSurfaceApi(),
+		composer: {
+			/** Attach or update context from this Work in the Cohub composer. */
+			setChip: (chip) => this.work.surface.setComposerChip(chip),
+			/** Remove context previously attached by this Work. */
+			clearChip: (key) => this.work.surface.clearComposerChip(key)
+		},
 		commerce: {
 			resolveProducts: async (input) => {
 				const context = await this.workRuntime.context();
@@ -1393,6 +1655,140 @@ var CohubClient = class {
 };
 const createCohubClient = (options) => new CohubClient(options);
 //#endregion
+//#region ../protocol/dist/public-identifiers.js
+const USERNAME_PATTERN = /^(?!-)(?!.*--)[a-z0-9-]{1,39}(?<!-)$/;
+const SPACE_SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9_-]{0,78}[a-z0-9])?$/;
+/**
+* Platform-owned path segments that must not be newly assigned to public
+* identities. Existing stored values remain readable through parse helpers.
+*/
+const RESERVED_PLATFORM_PATH_SEGMENTS = Object.freeze([
+	"admin",
+	"api",
+	"assets",
+	"auth",
+	"callback",
+	"changelog",
+	"docs",
+	"explore",
+	"invite",
+	"login",
+	"logout",
+	"new",
+	"org",
+	"pricing",
+	"pwa",
+	"referrals",
+	"sessions",
+	"settings",
+	"spaces",
+	"static",
+	"teams",
+	"trending",
+	"u",
+	"user",
+	"users",
+	"work-auth"
+]);
+new Set(RESERVED_PLATFORM_PATH_SEGMENTS);
+[...RESERVED_PLATFORM_PATH_SEGMENTS];
+function parseUsername(value) {
+	if (value === null || value === void 0) return null;
+	const normalized = value.trim().toLowerCase();
+	return USERNAME_PATTERN.test(normalized) ? normalized : null;
+}
+function parseSpaceSlug(value) {
+	if (value === null || value === void 0) return null;
+	const normalized = value.trim();
+	return SPACE_SLUG_PATTERN.test(normalized) ? normalized : null;
+}
+//#endregion
+//#region src/work-ref.ts
+/**
+* Accepts every way a Work is named across Cohub — id, management URL, public
+* URL, `cohub://works` URI, or `username/space/work` — and normalizes it.
+*
+* Public and mention forms may carry launch state (`?query#hash`); it is kept
+* separately so it can be forwarded to the Work while the stable identity stays
+* clean.
+*/
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const isWorkId = (value) => UUID_PATTERN.test(value.trim());
+function decodePart(value) {
+	try {
+		return decodeURIComponent(value).trim();
+	} catch {
+		return "";
+	}
+}
+function publicRef(parts) {
+	if (parts.length !== 3) return null;
+	const [usernameRaw = "", spaceSlugRaw = "", workSlugRaw = ""] = parts.map(decodePart);
+	const username = parseUsername(usernameRaw);
+	const spaceSlug = parseSpaceSlug(spaceSlugRaw);
+	const workSlug = parseSpaceSlug(workSlugRaw);
+	return username && spaceSlug && workSlug ? {
+		username,
+		spaceSlug,
+		workSlug
+	} : null;
+}
+function launchState(url) {
+	return {
+		...url.search ? { search: url.search } : {},
+		...url.hash ? { hash: url.hash } : {}
+	};
+}
+function parseUrlRef(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return null;
+	}
+	const parts = url.pathname.split("/").filter(Boolean);
+	if (url.protocol === "cohub:" && url.hostname === "works") {
+		const ref = publicRef(parts);
+		return ref ? {
+			...ref,
+			...launchState(url)
+		} : null;
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+	if (parts.length === 4 && parts[0] === "spaces" && UUID_PATTERN.test(parts[1] ?? "") && parts[2] === "works" && UUID_PATTERN.test(parts[3] ?? "")) return { id: parts[3] };
+	if (parts.length === 4 && parts[2] === "w") {
+		const ref = publicRef([
+			parts[0],
+			parts[1],
+			parts[3]
+		]);
+		return ref ? {
+			...ref,
+			...launchState(url)
+		} : null;
+	}
+	return null;
+}
+var WorkRefParseError = class extends Error {
+	constructor() {
+		super("Work must be an id, public URL, cohub://works URI, or username/space/work reference");
+		this.name = "WorkRefParseError";
+	}
+};
+function parseWorkRef(input) {
+	const value = input.trim();
+	if (UUID_PATTERN.test(value)) return { id: value };
+	const parsedUrl = parseUrlRef(value.includes("://") ? value : value.startsWith("/") ? `https://cohub.invalid${value}` : value);
+	if (parsedUrl) return parsedUrl;
+	const parts = value.split("/").filter(Boolean);
+	const parsedPublic = parts.length === 3 ? publicRef(parts) : null;
+	if (parsedPublic) return parsedPublic;
+	throw new WorkRefParseError();
+}
+function formatWorkRef(ref) {
+	return "id" in ref ? ref.id : `${ref.username}/${ref.spaceSlug}/${ref.workSlug}`;
+}
+//#endregion
 //#region src/work-grant-cache.ts
 const STORAGE_PREFIX = "cohub:work-grants";
 const CACHE_VERSION = 1;
@@ -2246,42 +2642,6 @@ z.discriminatedUnion("type", [
 	})
 ]);
 //#endregion
-//#region ../protocol/dist/public-identifiers.js
-/**
-* Platform-owned path segments that must not be newly assigned to public
-* identities. Existing stored values remain readable through parse helpers.
-*/
-const RESERVED_PLATFORM_PATH_SEGMENTS = Object.freeze([
-	"admin",
-	"api",
-	"assets",
-	"auth",
-	"callback",
-	"changelog",
-	"docs",
-	"explore",
-	"invite",
-	"login",
-	"logout",
-	"new",
-	"org",
-	"pricing",
-	"pwa",
-	"referrals",
-	"sessions",
-	"settings",
-	"spaces",
-	"static",
-	"teams",
-	"trending",
-	"u",
-	"user",
-	"users",
-	"work-auth"
-]);
-new Set(RESERVED_PLATFORM_PATH_SEGMENTS);
-[...RESERVED_PLATFORM_PATH_SEGMENTS];
-//#endregion
 //#region src/board/animation.ts
 const ZERO_COST = {
 	particles: 0,
@@ -2633,4 +2993,4 @@ function createBoardExtensionRegistry(input = {}) {
 	return registry;
 }
 //#endregion
-export { BILLING_ACCESS_BLOCKED_ERROR_CODE, BillingApi, BoardClient, BoardExtensionRegistry, BoardPlaybackPolicySchema, BoardTransactionError, COHUB_ENVIRONMENTS, COHUB_SOURCE_HEADER, COHUB_SOURCE_HEADER_NAMES, CohubClient, CohubHttpClient, DEFAULT_BOARD_LIMITS, FEATURE_NOT_ENTITLED_ERROR_CODE, GenerationPolicyError, HttpError, ParentBridgeTransport, PopupBrokerTransport, REQUEST_SOURCE_VIA_MAX_LENGTH, ReferencesApi, ReferralsApi, SessionGenerationStreamClient, SessionPatchReducer, UsersApi, VoiceApi, VoiceInputClient, WebsocketClient, WorkCommerceApi, WorkRealtimeApi, WorkRoom, WorkRuntimeApi, WorksApi, assertGenerationRequestAllowedByPolicy, buildSpaceInvitePath, buildSpacePath, clearGrantedWorkScopes, clip, compileSequence, createBoardExtensionRegistry, createCohubClient, createHttpClient, createSessionGenerationStreamClient, createSessionPatchReducer, createSlugWorkIdResolver, createVoiceInputClient, createWebsocketClient, createWorkBridgeCore, createWorkRuntime, decodeGenerationPolicy, encodeGenerationPolicy, extractBillingPayload, filterDiscoverableGenerationModels, filterGenerationDeclarationsByPolicy, findGenerationModelPolicy, getAllowedGenerationModelIds, hasGrantedWorkScopes, hasRequestSourceIdentity, isBillingAccessBlockedCode, isBillingAccessBlockedError, isFeatureNotEntitledError, isGenerationModelHidden, isHttpErrorCode, isRequestSourceEmpty, isRequestSourceUuid, joinApiUrl, matchesUnauthorizedErrorToken, mergeRequestSourceIntoMeta, normalizeBaseUrl, normalizeGenerationPolicy, normalizeRequestSource, normalizeVoiceInputWebsocketUrl, normalizeWebsocketUrl, parseAssistantMessageCommit, parseBoardPlaybackPolicy, parseGenerationPolicyFromEnv, parseRequestSourceFromHeaders, readRequestSourceFromEnv, requestSourceToHeaders, resolveApiBaseUrl, resolveCohubEnvironment, resolveRequestSourceChannel, resolveVoiceInputWebsocketUrl, resolveWebsocketUrl, resolveWorkTransport, sanitizeAccessToken, setGrantedWorkScopes, timeline };
+export { BILLING_ACCESS_BLOCKED_ERROR_CODE, BillingApi, BoardClient, BoardExtensionRegistry, BoardPlaybackPolicySchema, BoardTransactionError, COHUB_ENVIRONMENTS, COHUB_SOURCE_HEADER, COHUB_SOURCE_HEADER_NAMES, CohubClient, CohubHttpClient, DEFAULT_BOARD_LIMITS, FEATURE_NOT_ENTITLED_ERROR_CODE, GenerationPolicyError, HttpError, ParentBridgeTransport, PopupBrokerTransport, REQUEST_SOURCE_VIA_MAX_LENGTH, ReferencesApi, ReferralsApi, SessionGenerationStreamClient, SessionPatchReducer, UI_COMMAND_DEFAULT_TIMEOUT_MS, UI_COMMAND_MAX_TIMEOUT_MS, UI_COMMAND_PAYLOAD_MAX_BYTES, UI_COMMAND_PENDING_TTL_SECONDS, UI_COMMAND_SETTLEMENT_GRACE_SECONDS, UI_COMMAND_TERMINAL_TTL_SECONDS, UI_COMMAND_VERSION, UiCommandsApi, UsersApi, VoiceApi, VoiceInputClient, WORK_COMPOSER_CHIP_CONTENT_MAX_BYTES, WORK_COMPOSER_CHIP_KEY_MAX_LENGTH, WORK_COMPOSER_CHIP_LABEL_MAX_LENGTH, WORK_SURFACE_READY_TIMEOUT_MS, WORK_SURFACE_REQUEST_TIMEOUT_MS, WebsocketClient, WorkCommerceApi, WorkRealtimeApi, WorkRefParseError, WorkRoom, WorkRuntimeApi, WorkSurfaceApi, WorksApi, assertGenerationRequestAllowedByPolicy, buildSpaceInvitePath, buildSpacePath, buildWorkSurfaceRequest, clearGrantedWorkScopes, clip, compileSequence, createBoardExtensionRegistry, createCohubClient, createHttpClient, createSessionGenerationStreamClient, createSessionPatchReducer, createSlugWorkIdResolver, createVoiceInputClient, createWebsocketClient, createWorkBridgeCore, createWorkRuntime, decodeGenerationPolicy, encodeGenerationPolicy, extractBillingPayload, filterDiscoverableGenerationModels, filterGenerationDeclarationsByPolicy, findGenerationModelPolicy, formatWorkRef, getAllowedGenerationModelIds, hasGrantedWorkScopes, hasRequestSourceIdentity, isBillingAccessBlockedCode, isBillingAccessBlockedError, isFeatureNotEntitledError, isGenerationModelHidden, isHttpErrorCode, isRequestSourceClientId, isRequestSourceEmpty, isRequestSourceUuid, isTerminalUiCommandStatus, isUiSurfaceMethod, isWorkId, joinApiUrl, matchesUnauthorizedErrorToken, mergeRequestSourceIntoMeta, normalizeBaseUrl, normalizeGenerationPolicy, normalizeRequestSource, normalizeVoiceInputWebsocketUrl, normalizeWebsocketUrl, parseAssistantMessageCommit, parseBoardPlaybackPolicy, parseGenerationPolicyFromEnv, parseRequestSourceFromHeaders, parseUiCommand, parseWorkRef, parseWorkSurfaceReady, parseWorkSurfaceResponse, readRequestSourceFromEnv, requestSourceToHeaders, resolveApiBaseUrl, resolveCohubEnvironment, resolveRequestSourceChannel, resolveVoiceInputWebsocketUrl, resolveWebsocketUrl, resolveWorkTransport, sanitizeAccessToken, setGrantedWorkScopes, timeline };

package/dist/protocol/dist/provenance.js

@@ -5,6 +5,7 @@ const COHUB_SOURCE_HEADER = {
 	session: "X-Cohub-Source-Session",
 	turn: "X-Cohub-Source-Turn",
 	toolCall: "X-Cohub-Source-Tool-Call",
+	client: "X-Cohub-Source-Client",
 	via: "X-Cohub-Source-Via"
 };
 Object.values(COHUB_SOURCE_HEADER);

package/docs/work-runtime-guide.md

@@ -771,6 +771,38 @@ new one. The server keeps the participant ID, updates `room.participantId`, and
 closes the superseded connection without emitting a leave event. Without this
 mode, an unclean disconnect can retain its seat lease for up to one minute.
 
+#### UI command calls that complete later
+
+A `preview.show` command with a Surface request stays pending after the Work
+acknowledges it. The host waits for the Work to be mounted and ready, then the
+Work receives the originating `commandId` in the handler context and returns an
+acknowledgement immediately:
+
+```js
+let activeCommandId = null;
+
+client.work.surface.handle("image.open", async (input, { commandId }) => {
+  if (!commandId) throw new Error("image.open must be called by a UI command");
+  activeCommandId = commandId;
+  openImageStudio(input);
+  return { accepted: true };
+});
+
+async function useImage(result) {
+  if (!activeCommandId) return;
+  await client.ui.reportResult(activeCommandId, {
+    status: "applied",
+    result,
+    error: null,
+  });
+  activeCommandId = null;
+}
+```
+
+The Work should persist the command id alongside its local/server-backed draft
+so a reload can restore the pending interaction. A Work session may only report a command that targets that same Work. Existing
+`client.work.surface.handle(method, handler)` usage remains unchanged.
+
 ---
 
 ## 6. Complete working example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub",
-  "version": "5.2.0",
+  "version": "5.3.1",
   "description": "Cohub SDK for spaces, sessions, boards, and realtime agent collaboration.",
   "license": "Apache-2.0",
   "private": false,