@camerontaylor/paseo-protocol 0.8.0-fork.1

package/dist/chat/rpc-schemas.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { ChatMessageSchema, ChatRoomDetailSchema } from "./types.js";
+// COMPAT(chatRooms): retained after the v0.3.0 feature removal; remove after 2027-02-09 when mixed-version peers no longer send legacy messages.
+export const ChatCreateRequestSchema = z.object({
+    type: z.literal("chat/create"),
+    requestId: z.string(),
+    name: z.string(),
+    purpose: z.string().optional(),
+});
+export const ChatListRequestSchema = z.object({
+    type: z.literal("chat/list"),
+    requestId: z.string(),
+});
+export const ChatInspectRequestSchema = z.object({
+    type: z.literal("chat/inspect"),
+    requestId: z.string(),
+    room: z.string(),
+});
+export const ChatDeleteRequestSchema = z.object({
+    type: z.literal("chat/delete"),
+    requestId: z.string(),
+    room: z.string(),
+});
+export const ChatPostRequestSchema = z.object({
+    type: z.literal("chat/post"),
+    requestId: z.string(),
+    room: z.string(),
+    body: z.string(),
+    authorAgentId: z.string().optional(),
+    replyToMessageId: z.string().optional(),
+});
+export const ChatReadRequestSchema = z.object({
+    type: z.literal("chat/read"),
+    requestId: z.string(),
+    room: z.string(),
+    limit: z.number().int().nonnegative().optional(),
+    since: z.string().optional(),
+    authorAgentId: z.string().optional(),
+});
+export const ChatWaitRequestSchema = z.object({
+    type: z.literal("chat/wait"),
+    requestId: z.string(),
+    room: z.string(),
+    afterMessageId: z.string().optional(),
+    timeoutMs: z.number().int().nonnegative().optional(),
+});
+export const ChatCreateResponseSchema = z.object({
+    type: z.literal("chat/create/response"),
+    payload: z.object({
+        requestId: z.string(),
+        room: ChatRoomDetailSchema.nullable(),
+        error: z.string().nullable(),
+    }),
+});
+export const ChatListResponseSchema = z.object({
+    type: z.literal("chat/list/response"),
+    payload: z.object({
+        requestId: z.string(),
+        rooms: z.array(ChatRoomDetailSchema),
+        error: z.string().nullable(),
+    }),
+});
+export const ChatInspectResponseSchema = z.object({
+    type: z.literal("chat/inspect/response"),
+    payload: z.object({
+        requestId: z.string(),
+        room: ChatRoomDetailSchema.nullable(),
+        error: z.string().nullable(),
+    }),
+});
+export const ChatDeleteResponseSchema = z.object({
+    type: z.literal("chat/delete/response"),
+    payload: z.object({
+        requestId: z.string(),
+        room: ChatRoomDetailSchema.nullable(),
+        error: z.string().nullable(),
+    }),
+});
+export const ChatPostResponseSchema = z.object({
+    type: z.literal("chat/post/response"),
+    payload: z.object({
+        requestId: z.string(),
+        message: ChatMessageSchema.nullable(),
+        error: z.string().nullable(),
+    }),
+});
+export const ChatReadResponseSchema = z.object({
+    type: z.literal("chat/read/response"),
+    payload: z.object({
+        requestId: z.string(),
+        messages: z.array(ChatMessageSchema),
+        error: z.string().nullable(),
+    }),
+});
+export const ChatWaitResponseSchema = z.object({
+    type: z.literal("chat/wait/response"),
+    payload: z.object({
+        requestId: z.string(),
+        messages: z.array(ChatMessageSchema),
+        timedOut: z.boolean(),
+        error: z.string().nullable(),
+    }),
+});
+//# sourceMappingURL=rpc-schemas.js.map

package/dist/chat/types.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+export declare const ChatRoomSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    purpose: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type ChatRoom = z.infer<typeof ChatRoomSchema>;
+export declare const ChatMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    roomId: z.ZodString;
+    authorAgentId: z.ZodString;
+    body: z.ZodString;
+    replyToMessageId: z.ZodNullable<z.ZodString>;
+    mentionAgentIds: z.ZodArray<z.ZodString>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export type ChatMessage = z.infer<typeof ChatMessageSchema>;
+export declare const ChatRoomDetailSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    purpose: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    messageCount: z.ZodNumber;
+    lastMessageAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ChatRoomDetail = z.infer<typeof ChatRoomDetailSchema>;
+//# sourceMappingURL=types.d.ts.map

package/dist/chat/types.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+// COMPAT(chatRooms): retained after the v0.3.0 feature removal; remove after 2027-02-09 when mixed-version peers no longer send legacy messages.
+export const ChatRoomSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    purpose: z.string().nullable(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const ChatMessageSchema = z.object({
+    id: z.string(),
+    roomId: z.string(),
+    authorAgentId: z.string(),
+    body: z.string(),
+    replyToMessageId: z.string().nullable(),
+    mentionAgentIds: z.array(z.string()),
+    createdAt: z.string(),
+});
+export const ChatRoomDetailSchema = ChatRoomSchema.extend({
+    messageCount: z.number().int().nonnegative(),
+    lastMessageAt: z.string().nullable(),
+});
+//# sourceMappingURL=types.js.map

package/dist/check-traits.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Forge-neutral check traits carried on the wire alongside the stable check
+ * status union. Traits are open-ended by design (unknown values must be
+ * ignored by consumers); these constants cover the traits the shipped forges
+ * emit today so producers and the presentation layer cannot drift apart.
+ */
+export declare const CHECK_TRAIT_MANUAL = "manual";
+export declare const CHECK_TRAIT_ACTION_REQUIRED = "action_required";
+export declare const CHECK_TRAIT_WARNING = "warning";
+export type KnownCheckTrait = typeof CHECK_TRAIT_MANUAL | typeof CHECK_TRAIT_ACTION_REQUIRED | typeof CHECK_TRAIT_WARNING;
+//# sourceMappingURL=check-traits.d.ts.map

package/dist/check-traits.js

@@ -0,0 +1,10 @@
+/**
+ * Forge-neutral check traits carried on the wire alongside the stable check
+ * status union. Traits are open-ended by design (unknown values must be
+ * ignored by consumers); these constants cover the traits the shipped forges
+ * emit today so producers and the presentation layer cannot drift apart.
+ */
+export const CHECK_TRAIT_MANUAL = "manual";
+export const CHECK_TRAIT_ACTION_REQUIRED = "action_required";
+export const CHECK_TRAIT_WARNING = "warning";
+//# sourceMappingURL=check-traits.js.map

package/dist/client-capabilities.d.ts

@@ -0,0 +1,20 @@
+export declare const CLIENT_CAPS: {
+    readonly explicitEventSubscriptions: "explicit_event_subscriptions";
+    readonly allProviders: "all_providers";
+    readonly selectiveAgentTimeline: "selective_agent_timeline";
+    readonly reasoningMergeEnum: "reasoning_merge_enum";
+    readonly customModeIcons: "custom_mode_icons";
+    readonly terminalReflowableSnapshot: "terminal_reflowable_snapshot";
+    readonly providerSubagents: "provider_subagents";
+    readonly sideConversations: "side_conversations";
+    readonly projectUpdates: "project_updates";
+    readonly compactProviderSnapshots: "compact_provider_snapshots";
+    readonly providerSnapshotReferences: "provider_snapshot_references";
+    readonly timelineReplacementInvalidation: "timeline_replacement_invalidation";
+    readonly timelineNotifications: "timeline_notifications";
+    readonly pluginTimelineItems: "plugin_timeline_items";
+    readonly workspaceSetupBlocked: "workspace_setup_blocked";
+    readonly browserHost: "browser_host";
+};
+export type ClientCapability = (typeof CLIENT_CAPS)[keyof typeof CLIENT_CAPS];
+//# sourceMappingURL=client-capabilities.d.ts.map

package/dist/client-capabilities.js

@@ -0,0 +1,47 @@
+export const CLIENT_CAPS = {
+    // Clients outside the Paseo app version series can explicitly accept provider IDs.
+    // COMPAT(explicitEventSubscriptions): added in v0.8.0, remove legacy broadcasts after 2027-03-08.
+    explicitEventSubscriptions: "explicit_event_subscriptions",
+    allProviders: "all_providers",
+    // COMPAT(selectiveAgentTimeline): added in v0.1.106. Capable clients receive
+    // agent streams only for their explicit viewed set. Remove after 2027-01-12
+    // once the supported client floor is >= v0.1.106.
+    selectiveAgentTimeline: "selective_agent_timeline",
+    reasoningMergeEnum: "reasoning_merge_enum",
+    // COMPAT(customModeIcons): added in v0.1.84. Old clients pin AgentModeIcon to
+    // a closed enum and crash rendering unknown values; daemon downgrades icons
+    // outside the legacy set to "ShieldCheck" when this cap is absent. Drop the
+    // gate when floor >= v0.1.84.
+    customModeIcons: "custom_mode_icons",
+    // COMPAT(terminalReflowableSnapshot): added in v0.1.88. The daemon attaches
+    // per-row soft-wrap flags (gridWrapped/scrollbackWrapped) to terminal snapshots
+    // only when the client advertises this, so restored content can reflow on resize.
+    // Old clients use a strict TerminalState schema and would reject the extra fields.
+    // Drop the gate (always send the flags) when floor >= v0.1.88.
+    terminalReflowableSnapshot: "terminal_reflowable_snapshot",
+    // COMPAT(providerSubagents): added in v0.1.107. The daemon emits provider-owned
+    // child descriptors and timelines only to clients that understand the new messages.
+    providerSubagents: "provider_subagents",
+    // COMPAT(sideConversations): added in 0.7.0-beta.2.fork.1, fork-only — stock peers never gain it, so the gate lasts as long as stock peers are supported.
+    sideConversations: "side_conversations",
+    // COMPAT(projectUpdates): added in v0.1.109, remove gate after 2027-01-15.
+    projectUpdates: "project_updates",
+    // COMPAT(compactProviderSnapshots): added in v0.2.X. Capable clients receive
+    // provider catalogs with shared thinking sets and may revalidate by content hash.
+    // Remove the legacy snapshot encoding after 2027-02-04.
+    compactProviderSnapshots: "compact_provider_snapshots",
+    providerSnapshotReferences: "provider_snapshot_references",
+    // COMPAT(timelineReplacementInvalidation): added in v0.5.0, remove legacy
+    // reconstructed timeline replay after 2027-02-21 once the client floor supports invalidation.
+    timelineReplacementInvalidation: "timeline_replacement_invalidation",
+    // COMPAT(timelineNotifications): added in v0.7.2. The daemon omits notification
+    // timeline items for older clients whose strict timeline union rejects them.
+    // Remove after 2027-03-03 once the supported client floor is >= v0.7.2.
+    timelineNotifications: "timeline_notifications",
+    // COMPAT(pluginTimelineItems): added in v0.8.0, remove after 2027-03-07 once client floor >= v0.8.0.
+    pluginTimelineItems: "plugin_timeline_items",
+    // COMPAT(workspaceSetupBlocked): added in v0.8.0, remove after 2027-03-07 once client floor >= v0.8.0.
+    workspaceSetupBlocked: "workspace_setup_blocked",
+    browserHost: "browser_host",
+};
+//# sourceMappingURL=client-capabilities.js.map

package/dist/connection-offer.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+/**
+ * Relay-only pairing offer.
+ *
+ * `serverId` is a stable daemon identifier scoped to `PASEO_HOME`, and is also
+ * used as the relay session identifier.
+ */
+export declare const ConnectionOfferV2Schema: z.ZodObject<{
+    v: z.ZodLiteral<2>;
+    serverId: z.ZodString;
+    daemonPublicKeyB64: z.ZodString;
+    relay: z.ZodObject<{
+        endpoint: z.ZodString;
+        useTls: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ConnectionOfferV2 = z.infer<typeof ConnectionOfferV2Schema>;
+export declare const ConnectionOfferSchema: z.ZodObject<{
+    v: z.ZodLiteral<2>;
+    serverId: z.ZodString;
+    daemonPublicKeyB64: z.ZodString;
+    relay: z.ZodObject<{
+        endpoint: z.ZodString;
+        useTls: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ConnectionOffer = ConnectionOfferV2;
+export declare function decodeOfferFragmentPayload(encoded: string): unknown;
+/**
+ * Parse a pairing-offer URL of the form `https://app.paseo.sh/#offer=<base64url>`.
+ *
+ * Returns `null` if the input has no `#offer=` fragment. Throws if the fragment
+ * exists but the payload is malformed or fails schema validation.
+ */
+export declare function parseConnectionOfferFromUrl(input: string): ConnectionOffer | null;
+//# sourceMappingURL=connection-offer.d.ts.map

package/dist/connection-offer.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+/**
+ * Relay-only pairing offer.
+ *
+ * `serverId` is a stable daemon identifier scoped to `PASEO_HOME`, and is also
+ * used as the relay session identifier.
+ */
+export const ConnectionOfferV2Schema = z.object({
+    v: z.literal(2),
+    serverId: z.string().min(1),
+    daemonPublicKeyB64: z.string().min(1),
+    relay: z.object({
+        endpoint: z.string().min(1),
+        useTls: z.boolean().optional(),
+    }),
+});
+export const ConnectionOfferSchema = ConnectionOfferV2Schema;
+function decodeBase64UrlToUtf8(input) {
+    const base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), "=");
+    const binary = globalThis.atob(padded);
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+export function decodeOfferFragmentPayload(encoded) {
+    const json = decodeBase64UrlToUtf8(encoded);
+    return JSON.parse(json);
+}
+const OFFER_FRAGMENT_PREFIX = "#offer=";
+function extractOfferFragmentEncoded(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    const fragmentIndex = trimmed.indexOf(OFFER_FRAGMENT_PREFIX);
+    if (fragmentIndex === -1)
+        return null;
+    const encoded = trimmed.slice(fragmentIndex + OFFER_FRAGMENT_PREFIX.length).trim();
+    return encoded.length > 0 ? encoded : null;
+}
+/**
+ * Parse a pairing-offer URL of the form `https://app.paseo.sh/#offer=<base64url>`.
+ *
+ * Returns `null` if the input has no `#offer=` fragment. Throws if the fragment
+ * exists but the payload is malformed or fails schema validation.
+ */
+export function parseConnectionOfferFromUrl(input) {
+    const encoded = extractOfferFragmentEncoded(input);
+    if (!encoded)
+        return null;
+    const payload = decodeOfferFragmentPayload(encoded);
+    return ConnectionOfferSchema.parse(payload);
+}
+//# sourceMappingURL=connection-offer.js.map

package/dist/daemon-endpoints.d.ts

@@ -0,0 +1,47 @@
+export interface HostPortParts {
+    host: string;
+    port: number;
+    isIpv6: boolean;
+}
+export interface ConnectionUriParts extends HostPortParts {
+    useTls: boolean;
+}
+export interface ParsedConnectionUri extends ConnectionUriParts {
+    password?: string;
+}
+export type RelayRole = "server" | "client";
+export type RelayProtocolVersion = "1" | "2";
+export declare const CURRENT_RELAY_PROTOCOL_VERSION: RelayProtocolVersion;
+export declare const DEFAULT_RELAY_ENDPOINT = "relay.paseo.sh:443";
+export declare function normalizeRelayProtocolVersion(value: unknown, fallback?: RelayProtocolVersion): RelayProtocolVersion;
+export declare function parseHostPort(input: string): HostPortParts;
+export declare function normalizeHostPort(input: string): string;
+export declare function parseConnectionUri(input: string): ParsedConnectionUri;
+export declare function serializeConnectionUri(parts: ConnectionUriParts): string;
+export declare function serializeConnectionUriForStorage(parts: ParsedConnectionUri): string;
+export declare function normalizeLoopbackToLocalhost(endpoint: string): string;
+export declare function deriveLabelFromEndpoint(endpoint: string): string;
+export interface WebSocketUrlOptions {
+    useTls: boolean;
+}
+export declare function buildDaemonWebSocketUrl(endpoint: string, opts: WebSocketUrlOptions): string;
+export declare function buildRelayWebSocketUrl(params: {
+    endpoint: string;
+    useTls: boolean;
+    serverId: string;
+    role: RelayRole;
+    /**
+     * Per-connection routing identifier used by the daemon to open server data sockets.
+     * Clients should NOT provide this — the relay assigns a routing ID on connect.
+     */
+    connectionId?: string;
+    version?: RelayProtocolVersion | 1 | 2;
+}): string;
+/**
+ * @deprecated Migration fallback for stored relay connections/offers that predate
+ * explicit relay useTls. Delete after two release cycles.
+ */
+export declare function shouldUseTlsForDefaultHostedRelay(endpoint: string): boolean;
+export declare function extractHostPortFromWebSocketUrl(wsUrl: string): string;
+export declare function isRelayClientWebSocketUrl(url: string): boolean;
+//# sourceMappingURL=daemon-endpoints.d.ts.map

package/dist/daemon-endpoints.js

@@ -0,0 +1,201 @@
+export const CURRENT_RELAY_PROTOCOL_VERSION = "2";
+export const DEFAULT_RELAY_ENDPOINT = "relay.paseo.sh:443";
+export function normalizeRelayProtocolVersion(value, fallback = CURRENT_RELAY_PROTOCOL_VERSION) {
+    if (value == null) {
+        return fallback;
+    }
+    let normalized = "";
+    if (typeof value === "string") {
+        normalized = value.trim();
+    }
+    else if (typeof value === "number") {
+        normalized = String(value);
+    }
+    if (!normalized) {
+        return fallback;
+    }
+    if (normalized === "1" || normalized === "2") {
+        return normalized;
+    }
+    throw new Error('Relay version must be "1" or "2"');
+}
+function parsePort(portStr, context) {
+    const port = Number(portStr);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`${context}: port must be between 1 and 65535`);
+    }
+    return port;
+}
+export function parseHostPort(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new Error("Host is required");
+    }
+    // IPv6: [::1]:6767
+    if (trimmed.startsWith("[")) {
+        const match = trimmed.match(/^\[([^\]]+)\]:(\d{1,5})$/);
+        if (!match) {
+            throw new Error("Invalid host:port (expected [::1]:6767)");
+        }
+        const host = match[1].trim();
+        if (!host)
+            throw new Error("Host is required");
+        const port = parsePort(match[2], "Invalid host:port");
+        return { host, port, isIpv6: true };
+    }
+    const match = trimmed.match(/^(.+):(\d{1,5})$/);
+    if (!match) {
+        throw new Error("Invalid host:port (expected localhost:6767)");
+    }
+    const host = match[1].trim();
+    if (!host)
+        throw new Error("Host is required");
+    const port = parsePort(match[2], "Invalid host:port");
+    return { host, port, isIpv6: false };
+}
+export function normalizeHostPort(input) {
+    const { host, port, isIpv6 } = parseHostPort(input);
+    return isIpv6 ? `[${host}]:${port}` : `${host}:${port}`;
+}
+export function parseConnectionUri(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new Error("Connection URI is required");
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        throw new Error("Invalid connection URI");
+    }
+    if (parsed.protocol !== "tcp:") {
+        throw new Error("Connection URI protocol must be tcp:");
+    }
+    if (!parsed.hostname) {
+        throw new Error("Connection URI host is required");
+    }
+    if (!parsed.port) {
+        throw new Error("Connection URI port is required");
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error("Connection URI userinfo is not supported");
+    }
+    const isIpv6 = parsed.hostname.startsWith("[") && parsed.hostname.endsWith("]");
+    const host = isIpv6 ? parsed.hostname.slice(1, -1) : parsed.hostname;
+    const password = parsed.searchParams.get("password") || undefined;
+    return {
+        host,
+        port: parsePort(parsed.port, "Invalid connection URI"),
+        isIpv6,
+        useTls: parsed.searchParams.get("ssl") === "true",
+        ...(password ? { password } : {}),
+    };
+}
+export function serializeConnectionUri(parts) {
+    return createConnectionUri(parts).toString();
+}
+export function serializeConnectionUriForStorage(parts) {
+    const url = createConnectionUri(parts);
+    if (parts.password) {
+        url.searchParams.set("password", parts.password);
+    }
+    return url.toString();
+}
+function createConnectionUri(parts) {
+    const hostPart = parts.isIpv6 ? `[${parts.host}]` : parts.host;
+    const url = new URL(`tcp://${hostPart}:${parts.port}`);
+    if (parts.useTls) {
+        url.searchParams.set("ssl", "true");
+    }
+    return url;
+}
+export function normalizeLoopbackToLocalhost(endpoint) {
+    const { host, port, isIpv6 } = parseHostPort(endpoint);
+    if (host === "127.0.0.1" || (!isIpv6 && host === "0.0.0.0")) {
+        return `localhost:${port}`;
+    }
+    if (isIpv6 && (host === "::1" || host === "::")) {
+        return `localhost:${port}`;
+    }
+    return endpoint;
+}
+export function deriveLabelFromEndpoint(endpoint) {
+    try {
+        const { host } = parseHostPort(endpoint);
+        return host || "Unnamed Host";
+    }
+    catch {
+        return "Unnamed Host";
+    }
+}
+export function buildDaemonWebSocketUrl(endpoint, opts) {
+    const { host, port, isIpv6 } = parseHostPort(endpoint);
+    const protocol = opts.useTls ? "wss" : "ws";
+    const hostPart = isIpv6 ? `[${host}]` : host;
+    return new URL(`${protocol}://${hostPart}:${port}/ws`).toString();
+}
+export function buildRelayWebSocketUrl(params) {
+    const { host, port, isIpv6 } = parseHostPort(params.endpoint);
+    const protocol = params.useTls ? "wss" : "ws";
+    const hostPart = isIpv6 ? `[${host}]` : host;
+    const url = new URL(`${protocol}://${hostPart}:${port}/ws`);
+    url.searchParams.set("serverId", params.serverId);
+    url.searchParams.set("role", params.role);
+    url.searchParams.set("v", normalizeRelayProtocolVersion(params.version));
+    if (params.connectionId) {
+        url.searchParams.set("connectionId", params.connectionId);
+    }
+    return url.toString();
+}
+/**
+ * @deprecated Migration fallback for stored relay connections/offers that predate
+ * explicit relay useTls. Delete after two release cycles.
+ */
+export function shouldUseTlsForDefaultHostedRelay(endpoint) {
+    try {
+        const { port } = parseHostPort(endpoint);
+        return port === 443;
+    }
+    catch {
+        return false;
+    }
+}
+export function extractHostPortFromWebSocketUrl(wsUrl) {
+    const parsed = new URL(wsUrl);
+    if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
+        throw new Error("Invalid WebSocket URL protocol");
+    }
+    if (parsed.pathname.replace(/\/+$/, "") !== "/ws") {
+        throw new Error("Invalid WebSocket URL (expected /ws path)");
+    }
+    const host = parsed.hostname;
+    let port;
+    if (parsed.port) {
+        port = Number(parsed.port);
+    }
+    else if (parsed.protocol === "wss:") {
+        port = 443;
+    }
+    else {
+        port = 80;
+    }
+    if (!host) {
+        throw new Error("Invalid WebSocket URL (missing hostname)");
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error("Invalid WebSocket URL (invalid port)");
+    }
+    const isIpv6 = host.includes(":") && !host.startsWith("[") && !host.endsWith("]");
+    return isIpv6 ? `[${host}]:${port}` : `${host}:${port}`;
+}
+export function isRelayClientWebSocketUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.searchParams.get("role") === "client" && parsed.searchParams.has("serverId");
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=daemon-endpoints.js.map

package/dist/error-utils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Extracts a human-readable error message from an unknown error value.
+ * Handles Error instances, string errors, and other types safely.
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Extracts an error message from an unknown error value, with a fallback
+ * for when no message can be extracted.
+ */
+export declare function getErrorMessageOr(error: unknown, fallback: string): string;
+//# sourceMappingURL=error-utils.d.ts.map

package/dist/error-utils.js

@@ -0,0 +1,27 @@
+/**
+ * Extracts a human-readable error message from an unknown error value.
+ * Handles Error instances, string errors, and other types safely.
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === "string") {
+        return error;
+    }
+    return String(error);
+}
+/**
+ * Extracts an error message from an unknown error value, with a fallback
+ * for when no message can be extracted.
+ */
+export function getErrorMessageOr(error, fallback) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === "string" && error.length > 0) {
+        return error;
+    }
+    return fallback;
+}
+//# sourceMappingURL=error-utils.js.map