@xopcai/xopc 0.0.303 → 0.0.307

package/dist/gateway/static/root/index.html

@@ -11,7 +11,7 @@
     <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png?v=20260910-1" />
     <link rel="manifest" href="/site.webmanifest?v=20260910-1" />
     <title>XOPC — Keep what matters moving.</title>
-    <script type="module" crossorigin src="/assets/index-gheM453N.js"></script>
+    <script type="module" crossorigin src="/assets/index-RBCkv8a_.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-aKtaBQYM.js">
     <link rel="modulepreload" crossorigin href="/assets/preload-helper-zJ_50EbN.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-react-BOUWij0V.js">
@@ -25,38 +25,40 @@
     <link rel="modulepreload" crossorigin href="/assets/download-Dk-ZjtO6.js">
     <link rel="modulepreload" crossorigin href="/assets/plus-Q2yW6OE7.js">
     <link rel="modulepreload" crossorigin href="/assets/x-B_N4OPjy.js">
-    <link rel="modulepreload" crossorigin href="/assets/messages-C9h8SImu.js">
-    <link rel="modulepreload" crossorigin href="/assets/locale-store-DLK05Y1a.js">
+    <link rel="modulepreload" crossorigin href="/assets/messages-F74LVAiU.js">
+    <link rel="modulepreload" crossorigin href="/assets/locale-store-msTfRK8P.js">
     <link rel="modulepreload" crossorigin href="/assets/cn-JdwAhgNB.js">
     <link rel="modulepreload" crossorigin href="/assets/schemas-BaskVM5g.js">
     <link rel="modulepreload" crossorigin href="/assets/product-delivery-CCC4FJ3Y.js">
     <link rel="modulepreload" crossorigin href="/assets/app-link-BiBXVEvp.js">
     <link rel="modulepreload" crossorigin href="/assets/copy-to-clipboard-HOJ79TWv.js">
-    <link rel="modulepreload" crossorigin href="/assets/markdown-view-B8maDRWh.js">
+    <link rel="modulepreload" crossorigin href="/assets/markdown-view-BInabSKf.js">
     <link rel="modulepreload" crossorigin href="/assets/dist-Che_jiQF.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-swr-BIWyz7Rc.js">
     <link rel="modulepreload" crossorigin href="/assets/check-DUBLcKHA.js">
     <link rel="modulepreload" crossorigin href="/assets/skeleton-BwbyijEw.js">
     <link rel="modulepreload" crossorigin href="/assets/settings-shell-dialog-layer-BU3UuiJr.js">
     <link rel="modulepreload" crossorigin href="/assets/settings-shell-layer-context-DCp6ykjQ.js">
-    <link rel="modulepreload" crossorigin href="/assets/popover-select-DldSX8GX.js">
+    <link rel="modulepreload" crossorigin href="/assets/popover-select-9i-ZtHXL.js">
     <link rel="modulepreload" crossorigin href="/assets/circle-check-C23XjkUj.js">
     <link rel="modulepreload" crossorigin href="/assets/copy-Dv6d4Dvw.js">
     <link rel="modulepreload" crossorigin href="/assets/external-link-DjqjBmc3.js">
     <link rel="modulepreload" crossorigin href="/assets/globe-DSSGFWFn.js">
     <link rel="modulepreload" crossorigin href="/assets/loader-circle-CifKLtgG.js">
     <link rel="modulepreload" crossorigin href="/assets/middleware-Pd0e8Igk.js">
+    <link rel="modulepreload" crossorigin href="/assets/gateway-realtime-store-BLDgrJ30.js">
+    <link rel="modulepreload" crossorigin href="/assets/gateway-realtime-B53R0CA4.js">
     <link rel="modulepreload" crossorigin href="/assets/files-Be5viEFY.js">
     <link rel="modulepreload" crossorigin href="/assets/tool-activity-BtJkgjFf.js">
-    <link rel="modulepreload" crossorigin href="/assets/button-CGlRPNzi.js">
-    <link rel="modulepreload" crossorigin href="/assets/gateway-startup-retry-CSJWdnFs.js">
-    <link rel="modulepreload" crossorigin href="/assets/registry-api-BMFL4vis.js">
-    <link rel="modulepreload" crossorigin href="/assets/gateway-config-swr-D5AM8cyQ.js">
+    <link rel="modulepreload" crossorigin href="/assets/button-CS04eWY9.js">
+    <link rel="modulepreload" crossorigin href="/assets/gateway-startup-retry-DRzGnEV-.js">
+    <link rel="modulepreload" crossorigin href="/assets/registry-api-BSWtko7U.js">
+    <link rel="modulepreload" crossorigin href="/assets/gateway-config-swr-B6wHa6ZI.js">
     <link rel="modulepreload" crossorigin href="/assets/electron-env-Dit0bHgy.js">
-    <link rel="modulepreload" crossorigin href="/assets/activity-store-DCi5rh4e.js">
-    <link rel="modulepreload" crossorigin href="/assets/theme-store-KfFEGMlp.js">
+    <link rel="modulepreload" crossorigin href="/assets/activity-store-wgSB2HYK.js">
+    <link rel="modulepreload" crossorigin href="/assets/theme-store-1SZ-HFHX.js">
     <link rel="stylesheet" crossorigin href="/assets/markdown-view-Y68dCxuc.css">
-    <link rel="stylesheet" crossorigin href="/assets/index-BLRIcVQa.css">
+    <link rel="stylesheet" crossorigin href="/assets/index-cFU4S35z.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.0.303";
+var version = "0.0.307";
 //#endregion
 export { version };

package/dist/packages/gateway-contract/src/device-pairing.js

@@ -1,6 +1,80 @@
 import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
 import { z } from "zod";
 //#region packages/gateway-contract/src/device-pairing.ts
+function encodeBase64Url(bytes) {
+	let result = "";
+	for (let index = 0; index < bytes.length; index += 3) {
+		const a = bytes[index] ?? 0;
+		const b = bytes[index + 1] ?? 0;
+		const c = bytes[index + 2] ?? 0;
+		result += BASE64URL_ALPHABET[a >> 2];
+		result += BASE64URL_ALPHABET[(a & 3) << 4 | b >> 4];
+		if (index + 1 < bytes.length) result += BASE64URL_ALPHABET[(b & 15) << 2 | c >> 6];
+		if (index + 2 < bytes.length) result += BASE64URL_ALPHABET[c & 63];
+	}
+	return result;
+}
+function decodeBase64Url(value) {
+	if (!/^[A-Za-z0-9_-]*$/.test(value) || value.length % 4 === 1) throw new Error("Mobile pairing invitation is malformed");
+	const output = [];
+	let accumulator = 0;
+	let bits = 0;
+	for (const character of value) {
+		accumulator = accumulator << 6 | BASE64URL_ALPHABET.indexOf(character);
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			output.push(accumulator >> bits & 255);
+		}
+	}
+	const bytes = Uint8Array.from(output);
+	if (encodeBase64Url(bytes) !== value) throw new Error("Mobile pairing invitation is malformed");
+	return bytes;
+}
+function uuidToBytes(uuid) {
+	const hex = uuid.replaceAll("-", "");
+	if (!/^[0-9a-f]{32}$/i.test(hex)) throw new Error("Mobile pairing UUID is malformed");
+	return Uint8Array.from({ length: 16 }, (_, index) => Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16));
+}
+function asciiBytes(value) {
+	const bytes = Uint8Array.from(value, (character) => character.charCodeAt(0));
+	if (bytes.some((byte) => byte < 33 || byte > 126) || bytes.length !== value.length) throw new Error("Mobile pairing origin must be ASCII");
+	return bytes;
+}
+function formatMobilePairingInvitation(input) {
+	const invitation = mobilePairingInvitationSchema.parse(input);
+	const token = MOBILE_PAIRING_TOKEN.exec(invitation.pairingToken);
+	if (!token) throw new Error("Mobile pairing token is malformed");
+	const secret = decodeBase64Url(token[2]);
+	const publicKey = decodeBase64Url(invitation.gatewayPublicKey);
+	if (secret.length !== 32 || publicKey.length !== 32) throw new Error("Mobile pairing key is malformed");
+	const expiresAtSeconds = Math.floor(invitation.expiresAt / 1e3);
+	if (expiresAtSeconds > 4294967295) throw new Error("Mobile pairing expiry is out of range");
+	const origins = invitation.origins.map(asciiBytes);
+	if (origins.some((origin) => origin.length > 65535)) throw new Error("Mobile pairing origin is too long");
+	const bytes = new Uint8Array(MOBILE_INVITATION_FIXED_BYTES + origins.reduce((sum, origin) => sum + 2 + origin.length, 0));
+	const view = new DataView(bytes.buffer);
+	let offset = 0;
+	bytes[offset++] = 4;
+	bytes.set(uuidToBytes(token[1]), offset);
+	offset += 16;
+	bytes.set(secret, offset);
+	offset += 32;
+	bytes.set(uuidToBytes(invitation.gatewayId), offset);
+	offset += 16;
+	bytes.set(publicKey, offset);
+	offset += 32;
+	view.setUint32(offset, expiresAtSeconds);
+	offset += 4;
+	bytes[offset++] = origins.length;
+	for (const origin of origins) {
+		view.setUint16(offset, origin.length);
+		offset += 2;
+		bytes.set(origin, offset);
+		offset += origin.length;
+	}
+	return `${MOBILE_PAIRING_INVITATION_PREFIX}${encodeBase64Url(bytes)}`;
+}
 /** Browser invitations are opaque clipboard values, not navigable web links. */
 function formatBrowserPairingInvitation(encodedPayload) {
 	if (!/^[A-Za-z0-9_-]+$/.test(encodedPayload)) throw new Error("Browser pairing payload is invalid");
@@ -16,8 +90,9 @@ function buildDevicePairingProof(action, body) {
 	const { signature: _signature, ...payload } = body;
 	return `xopc-device-pairing-v3\nPOST\n${action}\n${canonical(payload)}`;
 }
-var BROWSER_PAIRING_INVITATION_PREFIX, devicePairingTargetKindSchema, devicePlatformSchema, devicePairingRouteSchema, devicePairingInvitationPayloadSchema, devicePairingKeySchema, devicePairingDeviceSchema, initialDeviceRefreshTokenSchema, devicePairingProofSchema, devicePairingRequestSchema, devicePairingCompleteSchema;
+var MOBILE_PAIRING_INVITATION_PREFIX, BROWSER_PAIRING_INVITATION_PREFIX, devicePairingTargetKindSchema, devicePlatformSchema, devicePairingRouteSchema, browserPairingInvitationPayloadSchema, secureMobileOriginSchema, mobilePairingInvitationSchema, BASE64URL_ALPHABET, MOBILE_PAIRING_TOKEN, MOBILE_INVITATION_FIXED_BYTES, devicePairingKeySchema, devicePairingDeviceSchema, initialDeviceRefreshTokenSchema, devicePairingProofSchema, devicePairingRequestSchema, devicePairingCompleteSchema;
 var init_device_pairing = __esmMin((() => {
+	MOBILE_PAIRING_INVITATION_PREFIX = "https://link.xopc.ai/c#";
 	BROWSER_PAIRING_INVITATION_PREFIX = `XOPC-BROWSER-INVITE-V1:`;
 	devicePairingTargetKindSchema = z.enum(["mobile", "browser"]);
 	devicePlatformSchema = z.enum([
@@ -44,22 +119,40 @@ var init_device_pairing = __esmMin((() => {
 			message: "Pairing route must be a secure origin"
 		});
 	});
-	devicePairingInvitationPayloadSchema = z.strictObject({
+	browserPairingInvitationPayloadSchema = z.strictObject({
 		version: z.literal(3),
-		targetKind: devicePairingTargetKindSchema,
+		targetKind: z.literal("browser"),
 		pairingToken: z.string().regex(/^xopc_pair_[0-9a-f-]{36}_[A-Za-z0-9_-]{43}$/i),
 		gatewayId: z.string().uuid(),
 		gatewayName: z.string().trim().min(1).max(120),
 		gatewayPublicKey: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
 		routes: z.array(devicePairingRouteSchema).min(1).max(8),
 		expiresAt: z.number().int().positive()
+	});
+	secureMobileOriginSchema = z.string().url().superRefine((origin, context) => {
+		const url = new URL(origin);
+		if (url.protocol !== "https:" || url.username || url.password || origin !== url.origin) context.addIssue({
+			code: "custom",
+			message: "Mobile pairing origins must be canonical HTTPS origins"
+		});
+	});
+	mobilePairingInvitationSchema = z.strictObject({
+		version: z.literal(4),
+		pairingToken: z.string().regex(/^xopc_pair_[0-9a-f-]{36}_[A-Za-z0-9_-]{43}$/i),
+		gatewayId: z.string().uuid(),
+		gatewayPublicKey: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+		origins: z.array(secureMobileOriginSchema).min(1).max(8),
+		expiresAt: z.number().int().positive()
 	}).superRefine((payload, context) => {
-		if (payload.targetKind === "mobile" && payload.routes.some((route) => route.kind === "local-browser")) context.addIssue({
+		if (new Set(payload.origins).size !== payload.origins.length) context.addIssue({
 			code: "custom",
-			path: ["routes"],
-			message: "Mobile invitations require remote routes"
+			path: ["origins"],
+			message: "Mobile pairing origins must be unique"
 		});
 	});
+	BASE64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+	MOBILE_PAIRING_TOKEN = /^xopc_pair_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})_([A-Za-z0-9_-]{43})$/i;
+	MOBILE_INVITATION_FIXED_BYTES = 102;
 	devicePairingKeySchema = z.strictObject({
 		kty: z.literal("EC"),
 		crv: z.literal("P-256"),
@@ -100,4 +193,4 @@ var init_device_pairing = __esmMin((() => {
 }));
 //#endregion
 init_device_pairing();
-export { BROWSER_PAIRING_INVITATION_PREFIX, buildDevicePairingProof, devicePairingCompleteSchema, devicePairingDeviceSchema, devicePairingInvitationPayloadSchema, devicePairingKeySchema, devicePairingProofSchema, devicePairingRequestSchema, devicePairingRouteSchema, devicePairingTargetKindSchema, devicePlatformSchema, formatBrowserPairingInvitation, init_device_pairing, initialDeviceRefreshTokenSchema };
+export { BROWSER_PAIRING_INVITATION_PREFIX, MOBILE_PAIRING_INVITATION_PREFIX, browserPairingInvitationPayloadSchema, buildDevicePairingProof, devicePairingCompleteSchema, devicePairingDeviceSchema, devicePairingKeySchema, devicePairingProofSchema, devicePairingRequestSchema, devicePairingRouteSchema, devicePairingTargetKindSchema, devicePlatformSchema, formatBrowserPairingInvitation, formatMobilePairingInvitation, init_device_pairing, initialDeviceRefreshTokenSchema, mobilePairingInvitationSchema };

package/dist/packages/gateway-contract/src/gateway-scopes.js

@@ -0,0 +1,53 @@
+import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
+//#region packages/gateway-contract/src/gateway-scopes.ts
+function isGatewayScope(value) {
+	return typeof value === "string" && KNOWN_GATEWAY_SCOPES.has(value);
+}
+var GATEWAY_SCOPES, KNOWN_GATEWAY_SCOPES, DEFAULT_MOBILE_SCOPES, DEFAULT_BROWSER_EXTENSION_SCOPES;
+var init_gateway_scopes = __esmMin((() => {
+	GATEWAY_SCOPES = [
+		"voice.configure",
+		"gateway.status",
+		"agents.read",
+		"agents.run",
+		"sessions.read",
+		"sessions.write",
+		"workspace.read",
+		"workspace.write",
+		"tasks.read",
+		"tasks.write",
+		"automations.read",
+		"automations.write",
+		"notifications.self",
+		"device.self",
+		"gateway.admin"
+	];
+	KNOWN_GATEWAY_SCOPES = new Set(GATEWAY_SCOPES);
+	DEFAULT_MOBILE_SCOPES = [
+		"voice.configure",
+		"gateway.status",
+		"agents.read",
+		"agents.run",
+		"sessions.read",
+		"sessions.write",
+		"workspace.read",
+		"workspace.write",
+		"tasks.read",
+		"tasks.write",
+		"automations.read",
+		"automations.write",
+		"notifications.self",
+		"device.self"
+	];
+	DEFAULT_BROWSER_EXTENSION_SCOPES = [
+		"gateway.status",
+		"agents.read",
+		"agents.run",
+		"sessions.read",
+		"sessions.write",
+		"device.self"
+	];
+}));
+//#endregion
+init_gateway_scopes();
+export { DEFAULT_BROWSER_EXTENSION_SCOPES, DEFAULT_MOBILE_SCOPES, GATEWAY_SCOPES, init_gateway_scopes, isGatewayScope };

package/dist/packages/gateway-contract/src/index.js

@@ -21,6 +21,7 @@ import { init_notifications } from "./notifications.js";
 import { init_files } from "./files.js";
 import { init_mobile_privacy } from "./mobile-privacy.js";
 import { init_device_pairing } from "./device-pairing.js";
+import { init_gateway_scopes } from "./gateway-scopes.js";
 import { init_browser_page_context } from "./browser-page-context.js";
 import { init_browser_tab_binding } from "./browser-tab-binding.js";
 import { init_model_selection } from "./model-selection.js";
@@ -52,6 +53,7 @@ var init_src = __esmMin((() => {
 	init_files();
 	init_mobile_privacy();
 	init_device_pairing();
+	init_gateway_scopes();
 	init_browser_page_context();
 	init_browser_tab_binding();
 	init_model_selection();

package/dist/packages/realtime-client/src/index.js

@@ -1,4 +1,4 @@
-import { parseServerRealtimeMessage } from "../../realtime-protocol/src/index.js";
+import { REALTIME_CAPABILITIES, parseServerRealtimeMessage } from "../../realtime-protocol/src/index.js";
 //#region packages/realtime-client/src/index.ts
 var RealtimeConnectionError = class extends Error {
 	constructor(message, retryable) {
@@ -34,6 +34,7 @@ var RealtimeClient = class {
 	lastServerMessageAt = 0;
 	endpointBinding;
 	reconnectWhenSocketOpens = false;
+	offeredCapabilities = /* @__PURE__ */ new Set();
 	constructor(options) {
 		this.options = options;
 	}
@@ -48,6 +49,7 @@ var RealtimeClient = class {
 		this.generation += 1;
 		this.clearTimers();
 		this.ready = false;
+		this.offeredCapabilities.clear();
 		this.endpointBinding?.onDisconnected?.();
 		this.socket?.close(1e3, "Client disconnected");
 		this.socket = void 0;
@@ -116,6 +118,7 @@ var RealtimeClient = class {
 			ticketAbort.abort();
 			if (this.ticketAbort === ticketAbort) this.ticketAbort = void 0;
 			this.ready = false;
+			this.offeredCapabilities.clear();
 			this.endpointBinding?.onDisconnected?.();
 			this.clearHeartbeat();
 			if (this.socket === socket) this.socket = void 0;
@@ -135,8 +138,13 @@ var RealtimeClient = class {
 		this.connectionTimer = setTimeout(() => failAttempt("Realtime connection timed out"), timeoutMs);
 		this.options.onStateChange?.(reconnecting ? "reconnecting" : "connecting");
 		try {
-			const [ticket, endpoint] = await Promise.all([this.options.issueTicket(ticketAbort.signal), this.endpointBinding?.createHello()]);
+			const [issuedTicket, endpoint] = await Promise.all([this.options.issueTicket(ticketAbort.signal), this.endpointBinding?.createHello()]);
+			const ticket = issuedTicket.ticket;
+			if (2 < issuedTicket.realtime.minVersion) throw new RealtimeConnectionError("CLIENT_UPDATE_REQUIRED", false);
+			if (2 > issuedTicket.realtime.maxVersion) throw new RealtimeConnectionError("GATEWAY_UPDATE_REQUIRED", false);
+			const capabilities = REALTIME_CAPABILITIES.filter((capability) => issuedTicket.realtime.capabilities.includes(capability));
 			if (closed || !this.shouldReconnect || generation !== this.generation) return;
+			this.offeredCapabilities = new Set(capabilities ?? []);
 			socket = this.options.createWebSocket(this.options.getWebSocketUrl());
 			this.socket = socket;
 			socket.onopen = () => {
@@ -154,6 +162,7 @@ var RealtimeClient = class {
 					clientId: this.options.clientId,
 					clientKind: this.options.clientKind,
 					subscriptions,
+					...capabilities?.length ? { capabilities } : {},
 					...endpoint ? { endpoint } : {}
 				}));
 			};
@@ -195,11 +204,14 @@ var RealtimeClient = class {
 		const message = parseServerRealtimeMessage(JSON.parse(text));
 		this.lastServerMessageAt = Date.now();
 		if (message.kind === "realtime.ready") {
+			const negotiated = message.payload.negotiatedCapabilities ?? [];
+			if (negotiated.some((capability) => !this.offeredCapabilities.has(capability))) throw new Error("Realtime server negotiated a capability the client did not offer");
 			this.ready = true;
 			this.reconnectAttempts = 0;
 			this.clearConnectionTimer();
 			this.ticketAbort = void 0;
 			this.options.onStateChange?.("connected");
+			this.options.onCapabilities?.(negotiated);
 			if (message.payload.endpoint) this.endpointBinding?.onReady(message.payload.endpoint);
 			this.clearHeartbeat();
 			this.heartbeatTimer = setInterval(() => {

package/dist/packages/realtime-protocol/src/index.js

@@ -6,6 +6,7 @@ const REALTIME_MAX_CLIENT_FRAME_BYTES = 256 * 1024;
 const REALTIME_HELLO_TIMEOUT_MS = 5e3;
 const REALTIME_HEARTBEAT_INTERVAL_MS = 15e3;
 const REALTIME_HEARTBEAT_TIMEOUT_MS = 45e3;
+const REALTIME_CAPABILITIES = ["realtime.capability-negotiation.v1"];
 const realtimeClientKindSchema = z.enum([
 	"web",
 	"desktop",
@@ -19,59 +20,62 @@ const realtimeEventNameSchema = z.string().regex(/^[a-z][a-z0-9_.-]*$/).max(160)
 const messageIdSchema = z.uuid();
 const timestampSchema = z.number().int().nonnegative();
 const sequenceSchema = z.number().int().positive();
-const envelope = (kind, payload) => z.strictObject({
+const capabilitySchema = z.string().min(1).max(160);
+const envelope = (kind, payload) => z.object({
 	protocolVersion: z.literal(2),
 	messageId: messageIdSchema,
 	kind: z.literal(kind),
 	sentAt: timestampSchema,
 	payload
 });
-const realtimeSubscriptionSchema = z.strictObject({
+const realtimeSubscriptionSchema = z.object({
 	topic: realtimeTopicSchema,
 	afterSeq: z.number().int().nonnegative().optional()
 });
 const clientRealtimeMessageSchema = z.discriminatedUnion("kind", [
-	envelope("realtime.hello", z.strictObject({
+	envelope("realtime.hello", z.object({
 		ticket: z.string().min(32).max(512),
 		clientId: z.string().min(1).max(160),
 		clientKind: realtimeClientKindSchema,
 		subscriptions: z.array(realtimeSubscriptionSchema).max(100).default([]),
+		capabilities: z.array(capabilitySchema).max(64).optional(),
 		endpoint: endpointHelloPayloadSchema.optional()
 	})),
-	envelope("realtime.subscribe", z.strictObject({ subscriptions: z.array(realtimeSubscriptionSchema).min(1).max(100) })),
-	envelope("realtime.unsubscribe", z.strictObject({ topics: z.array(realtimeTopicSchema).min(1).max(100) })),
-	envelope("realtime.ping", z.strictObject({})),
+	envelope("realtime.subscribe", z.object({ subscriptions: z.array(realtimeSubscriptionSchema).min(1).max(100) })),
+	envelope("realtime.unsubscribe", z.object({ topics: z.array(realtimeTopicSchema).min(1).max(100) })),
+	envelope("realtime.ping", z.object({})),
 	envelope("endpoint.message", clientEndpointMessageSchema)
 ]);
-const realtimeEventPayloadSchema = z.strictObject({
+const realtimeEventPayloadSchema = z.object({
 	topic: realtimeTopicSchema,
 	seq: sequenceSchema,
 	event: realtimeEventNameSchema,
 	data: z.unknown()
 });
 const serverRealtimeMessageSchema = z.discriminatedUnion("kind", [
-	envelope("realtime.ready", z.strictObject({
+	envelope("realtime.ready", z.object({
 		connectionId: z.uuid(),
 		heartbeatIntervalMs: z.literal(REALTIME_HEARTBEAT_INTERVAL_MS),
 		heartbeatTimeoutMs: z.literal(REALTIME_HEARTBEAT_TIMEOUT_MS),
-		endpoint: z.strictObject({
+		negotiatedCapabilities: z.array(capabilitySchema).max(64).optional(),
+		endpoint: z.object({
 			endpointId: z.string().min(1).max(160),
 			turnToken: z.string().min(32).max(160)
 		}).optional()
 	})),
 	envelope("realtime.event", realtimeEventPayloadSchema),
-	envelope("realtime.subscribed", z.strictObject({
+	envelope("realtime.subscribed", z.object({
 		topic: realtimeTopicSchema,
 		cursor: z.number().int().nonnegative()
 	})),
-	envelope("realtime.gap", z.strictObject({
+	envelope("realtime.gap", z.object({
 		topic: realtimeTopicSchema,
 		requestedSeq: z.number().int().nonnegative(),
 		earliestSeq: sequenceSchema,
 		recoverable: z.boolean()
 	})),
-	envelope("realtime.pong", z.strictObject({})),
-	envelope("realtime.error", z.strictObject({
+	envelope("realtime.pong", z.object({})),
+	envelope("realtime.error", z.object({
 		code: z.string().min(1).max(80),
 		message: z.string().min(1).max(500)
 	})),
@@ -88,4 +92,4 @@ function parseClientRealtimeJsonFrame(text) {
 	return JSON.parse(text);
 }
 //#endregion
-export { REALTIME_HEARTBEAT_INTERVAL_MS, REALTIME_HEARTBEAT_TIMEOUT_MS, REALTIME_HELLO_TIMEOUT_MS, REALTIME_MAX_CLIENT_FRAME_BYTES, parseClientRealtimeJsonFrame, parseClientRealtimeMessage, parseServerRealtimeMessage, realtimeClientKindSchema, realtimeEventNameSchema, realtimeTopicSchema };
+export { REALTIME_CAPABILITIES, REALTIME_HEARTBEAT_INTERVAL_MS, REALTIME_HEARTBEAT_TIMEOUT_MS, REALTIME_HELLO_TIMEOUT_MS, REALTIME_MAX_CLIENT_FRAME_BYTES, parseClientRealtimeJsonFrame, parseClientRealtimeMessage, parseServerRealtimeMessage, realtimeClientKindSchema, realtimeEventNameSchema, realtimeTopicSchema };

package/dist/src/agent/agent-instance-gateway.d.ts

@@ -37,6 +37,8 @@ export interface AgentInstanceGateway {
     getAgent(conversationId: string): Agent | undefined;
     /** Returns true when an agent instance existed for `conversationId` and was removed. */
     removeAgent(conversationId: string): boolean;
+    /** Finish loading and initialize memory providers before agent construction or recall. */
+    ensureMemoryReadyForSession?(conversationId: string): Promise<void>;
     /** Create isolated policy state for one user-visible agent run. */
     createAgentTurnPolicy(conversationId: string): AgentTurnPolicy;
     /** Publish events from the actual embedded runtime to session observers. */

package/dist/src/agent/agent-manager.d.ts

@@ -164,6 +164,7 @@ export declare class AgentManager implements AgentInstanceGateway {
     private skillsUpdatedTimer;
     private pendingSkillsUpdatedReason;
     private projectTrustStore;
+    private memoryPromptReady;
     constructor(config: AgentManagerConfig);
     private isUserContextEnabledForSession;
     private computeBaseWorkspacePath;
@@ -199,6 +200,7 @@ export declare class AgentManager implements AgentInstanceGateway {
     private buildToolsFactoryDeps;
     getMemoryManager(): MemoryManager;
     getMemoryManagerForSession(conversationId: string): MemoryManager;
+    ensureMemoryReadyForSession(conversationId: string): Promise<void>;
     /** Build the bounded, policy-filtered context used for this model turn. */
     prepareUserTurnContext(userMessage: AgentMessage, conversationId: string, turnId: string): Promise<ExecutionContextPlan>;
     /** Capture durable structured user context after a completed turn. */

package/dist/src/agent/agent-manager.js

@@ -121,6 +121,7 @@ var AgentManager = class {
 	skillsUpdatedTimer;
 	pendingSkillsUpdatedReason;
 	projectTrustStore = new ProjectTrustStore();
+	memoryPromptReady = /* @__PURE__ */ new WeakMap();
 	constructor(config) {
 		this.config = config;
 		this.baseWorkspacePath = this.computeBaseWorkspacePath();
@@ -141,7 +142,19 @@ var AgentManager = class {
 			getConfig: () => this.config.config,
 			getAccessForSession: (conversationId) => resolveUserContextSessionAccess(this.config.config, conversationId),
 			getWorkspaceIdForSession: (sk) => this.getResolvedWorkspaceForSession(sk),
-			getProjectIdForSession: (sk) => getSessionMetadata(sk)?.projectId
+			getProjectIdForSession: (sk) => getSessionMetadata(sk)?.projectId,
+			ensureMemoryReady: (conversationId) => this.ensureMemoryReadyForSession(conversationId),
+			searchExternalMemory: async (input) => this.getMemoryManagerForSession(input.conversationId).searchExternal({
+				query: input.query,
+				scope: {
+					userId: "local-owner",
+					workspaceId: input.workspaceId,
+					conversationId: input.conversationId,
+					...input.projectId ? { projectId: input.projectId } : {}
+				},
+				trustedOnly: true,
+				maxResults: input.maxResults
+			})
 		});
 		this.backgroundReview = new BackgroundReviewCoordinator({ getConfig: () => this.mergedConfig() });
 		this.toolsFactory = new AgentToolsFactory(this.buildToolsFactoryDeps());
@@ -292,8 +305,30 @@ var AgentManager = class {
 	getMemoryManagerForSession(conversationId) {
 		return this.getWorkspaceRuntimeForSession(conversationId).memoryManager;
 	}
+	async ensureMemoryReadyForSession(conversationId) {
+		const cfg = this.config.config;
+		if (!cfg || !isMemorySubsystemEnabled(cfg)) return;
+		const resolvedPath = this.getResolvedWorkspaceForSession(conversationId);
+		const profile = resolveEffectiveAgentProfileForSession(cfg, conversationId);
+		const runtime = this.workspaceRuntimes.getOrCreate(resolvedPath, profile.agentId);
+		await runtime.memoryManager.initializeAll(conversationId, {
+			workspace: resolvedPath,
+			agentWorkspace: resolveAgentProfileDir(cfg, profile.agentId),
+			agentId: profile.agentId,
+			sessionId: conversationId
+		});
+		let readySessions = this.memoryPromptReady.get(runtime.memoryManager);
+		if (!readySessions) {
+			readySessions = /* @__PURE__ */ new Set();
+			this.memoryPromptReady.set(runtime.memoryManager, readySessions);
+		}
+		if (readySessions.has(conversationId)) return;
+		readySessions.add(conversationId);
+		const existing = this.agents.get(conversationId);
+		if (existing) this.refreshDynamicContextIfChanged(existing, true);
+	}
 	/** Build the bounded, policy-filtered context used for this model turn. */
-	prepareUserTurnContext(userMessage, conversationId, turnId) {
+	async prepareUserTurnContext(userMessage, conversationId, turnId) {
 		return this.executionContext.prepare(userMessage, conversationId, turnId);
 	}
 	/** Capture durable structured user context after a completed turn. */
@@ -722,13 +757,6 @@ var AgentManager = class {
 		const resolvedPath = targetPath;
 		const rt = this.workspaceRuntimes.getOrCreate(resolvedPath, profile.agentId);
 		profile = this.materializeSkillAllowlist(profile, rt);
-		if (isMemorySubsystemEnabled(cfg)) rt.memoryManager.initializeAll(conversationId, {
-			workspace: resolvedPath,
-			agentId: profile.agentId
-		}).catch((err) => log.warn({
-			err,
-			conversationId
-		}, "memory initializeAll failed"));
 		const activeProjectContext = this.buildExecutionScopeContext(conversationId);
 		const profileModelRef = profile.primaryModelRef?.trim() || this.defaultModel;
 		const modelManager = this.config.getModelManager?.();
@@ -912,7 +940,7 @@ var AgentManager = class {
 		const access = resolveUserContextSessionAccess(this.config.config, conversationId);
 		return buildExecutionScopeContextForPrompt(conversationId, {
 			includeKnowledge: access.knowledge,
-			knowledgeSources: access.knowledgeSources
+			knowledgePolicy: access.knowledgePolicy
 		});
 	}
 	getInteractionStateVersion(conversationId) {
@@ -1094,11 +1122,11 @@ var AgentManager = class {
 		}));
 		return result.status === "answered" && result.answer === "Allow once";
 	}
-	refreshDynamicContextIfChanged(instance) {
+	refreshDynamicContextIfChanged(instance, force = false) {
 		const nextProjectContext = this.buildExecutionScopeContext(instance.conversationId);
 		const interactionStateVersion = this.getInteractionStateVersion(instance.conversationId);
 		const userContextAccessVersion = this.getUserContextAccessVersion(instance.conversationId);
-		if (nextProjectContext === instance.activeProjectContext && interactionStateVersion === instance.interactionStateVersion && userContextAccessVersion === instance.userContextAccessVersion) return;
+		if (!force && nextProjectContext === instance.activeProjectContext && interactionStateVersion === instance.interactionStateVersion && userContextAccessVersion === instance.userContextAccessVersion) return;
 		const cfg = this.config.config;
 		const resolvedWorkspacePath = this.getResolvedWorkspaceForSession(instance.conversationId);
 		const rt = this.workspaceRuntimes.getOrCreate(resolvedWorkspacePath, instance.effectiveProfile.agentId);

package/dist/src/agent/agent-scope.d.ts

@@ -7,10 +7,13 @@ export declare const DEFAULT_AGENT_ID = "main";
 export declare const STRICT_AGENT_ID_RE: RegExp;
 /** Path-safe agent id. */
 export declare function normalizeAgentId(value: string | undefined | null): string;
+/** Derive a folder-safe id, including for display names with no ASCII characters. */
+export declare function deriveAgentIdFromDisplayName(displayName: string): string;
 /**
  * Validate agent id for new agents (folder-safe path segment).
  * When `explicitId` is set, it must already match {@link STRICT_AGENT_ID_RE} (case-insensitive input, stored lowercase).
- * When omitted, id is derived from `displayNameForDerivation` via {@link normalizeAgentId}.
+ * When omitted, id is derived from `displayNameForDerivation`, with a stable hashed fallback
+ * for names that contain no ASCII id characters.
  */
 export declare function validateAgentIdForNewAgent(explicitId: string | undefined | null, displayNameForDerivation: string): {
     ok: true;

package/dist/src/agent/agent-scope.js

@@ -19,10 +19,26 @@ function normalizeAgentId(value) {
 	if (VALID_ID_RE.test(trimmed)) return normalized;
 	return normalized.replace(INVALID_CHARS_RE, "-").replace(LEADING_DASH_RE, "").replace(TRAILING_DASH_RE, "").slice(0, 64) || "main";
 }
+function hashAgentDisplayName(value) {
+	let hash = 2166136261;
+	for (let index = 0; index < value.length; index += 1) {
+		hash ^= value.charCodeAt(index);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(36).padStart(7, "0");
+}
+/** Derive a folder-safe id, including for display names with no ASCII characters. */
+function deriveAgentIdFromDisplayName(displayName) {
+	const normalizedName = displayName.trim().normalize("NFKC").toLowerCase();
+	const asciiId = normalizeAgentId(normalizedName);
+	if (asciiId !== "main" || normalizedName === "main") return asciiId;
+	return normalizedName ? `agent-${hashAgentDisplayName(normalizedName)}` : DEFAULT_AGENT_ID;
+}
 /**
 * Validate agent id for new agents (folder-safe path segment).
 * When `explicitId` is set, it must already match {@link STRICT_AGENT_ID_RE} (case-insensitive input, stored lowercase).
-* When omitted, id is derived from `displayNameForDerivation` via {@link normalizeAgentId}.
+* When omitted, id is derived from `displayNameForDerivation`, with a stable hashed fallback
+* for names that contain no ASCII id characters.
 */
 function validateAgentIdForNewAgent(explicitId, displayNameForDerivation) {
 	const explicit = explicitId?.trim();
@@ -45,7 +61,7 @@ function validateAgentIdForNewAgent(explicitId, displayNameForDerivation) {
 			agentId: id
 		};
 	}
-	const agentId = normalizeAgentId(displayNameForDerivation.trim());
+	const agentId = deriveAgentIdFromDisplayName(displayNameForDerivation);
 	if (agentId === "main") return {
 		ok: false,
 		error: "Display name cannot produce a valid agent folder id. Set an explicit Agent id (letters, digits, underscores, hyphens only)."
@@ -212,4 +228,4 @@ var init_agent_scope = __esmMin((() => {
 }));
 //#endregion
 init_agent_scope();
-export { DEFAULT_AGENT_ID, STRICT_AGENT_ID_RE, getDefaultWorkspacePath, init_agent_scope, listAgentEntries, normalizeAgentId, resolveAgentDir, resolveAgentHomeDir, resolveAgentIdByWorkspacePath, resolveAgentIdForWorkspacePath, resolveAgentIdsByWorkspacePath, resolveAgentProfileDir, resolveAgentProfileMarkdownPath, resolveAgentWorkspaceDir, resolveDefaultAgentId, resolveUserPath, validateAgentIdForNewAgent };
+export { DEFAULT_AGENT_ID, STRICT_AGENT_ID_RE, deriveAgentIdFromDisplayName, getDefaultWorkspacePath, init_agent_scope, listAgentEntries, normalizeAgentId, resolveAgentDir, resolveAgentHomeDir, resolveAgentIdByWorkspacePath, resolveAgentIdForWorkspacePath, resolveAgentIdsByWorkspacePath, resolveAgentProfileDir, resolveAgentProfileMarkdownPath, resolveAgentWorkspaceDir, resolveDefaultAgentId, resolveUserPath, validateAgentIdForNewAgent };